Utcnow

* Included inline documentation for the functions and parts developers may touch in this library.
* Added modifier and timediff support for milliseconds, microseconds and nanoseconds _(although nanosecond precision will currently not use native nanoseconds, and will return microseconds * 1000)_. See details in [133](https://github.com/kalaspuff/utcnow/pull/133).
* Refactoring of the library to actually use a `ModuleType` instead of creating a class object (that was used as as a drop in for the module) when importing `utcnow`.
* Addition of a context manager available at `utcnow.synchronizer` to freeze the current time of `utcnow` to a specific value of your choice or to the current time when entering the context manager. See details in [133](https://github.com/kalaspuff/utcnow/pull/133) and the [repo documentation](https://github.com/kalaspuff/utcnow?tab=readme-ov-file#freeze-the-current-time-in-utcnow-with-utcnowsynchronizer).

* Support for Python 3.12.

* Added support to transform from (and if necessary, to) Protocol Buffers messages of type `google.protobuf.Timestamp` as well as from binary data representing a `google.protobuf.Timestamp` protobuf message. (see additional info below).
* Support for timezones delta used with a whitespace before specification (for example `"2022-12-06T13:37:34.037042 +01:00"` works the same as `"2022-12-06T13:37:34.037042+01:00"`)

---

Possible to transform a value encoded as a `google.protobuf.Timestamp` protobuf message in the same way you would from any other value.

python
Using a google.protobuf.Timestamp message as input to utcnow
import utcnow
from google.protobuf.timestamp_pb2 import Timestamp
msg = Timestamp(seconds=1670329924, nanos=170660000)
result = utcnow.get(msg)
"2022-12-06T12:32:04.170660Z"


python
Using the binary data from a google.protobuf.Timestamp message
import utcnow
protobuf_msg_binary = b"\x08\xc4\xec\xbc\x9c\x06\x10\xa0\xa1\xb0Q"
result = utcnow.get(protobuf_msg_binary)
"2022-12-06T12:32:04.170660Z"


You can also generate a new `google.protobuf.Timestamp` message using `utcnow.as_protobuf()`

python
import utcnow
msg = utcnow.as_protobuf("1984-08-01 22:30:47.234003Z")
<class 'google.protobuf.timestamp_pb2.Timestamp'>
· seconds: 460247447
· nanos: 234003000


Note that the `protobuf` package has to be installed to make use of the above functionality. For convenience, it's also possible to install `utcnow` with `protobuf` support using the `protobuf` extras.


$ pip install utcnow[protobuf]

* Python 3.11 added to test matrix and trove classifiers to officially claim support.

* Added optional modifier argument to the timestamp functions.

python
import utcnow

utcnow.rfc3339_timestamp("2000-01-01", "+30s")
2000-01-01T00:00:30.000000Z

utcnow.rfc3339_timestamp("2000-01-01", "-1d")
1999-12-31T00:00:00.000000Z

utcnow.rfc3339_timestamp("2022-10-17 15:30:00", "+5.5h")
2022-10-17T21:00:00.000000Z

utcnow.rfc3339_timestamp("now", "+365d")
2023-10-17T15:26:55.706575Z

* `utcnow` can now be used as cli by installing `utcnow-cli` or using the `cli` extras of `utcnow`.

bash
install utcnow with extras: cli
pip install utcnow[cli]
equivalent to installing utcnow-cli
pip install utcnow-cli



code ~$ utcnow
2022-10-17T14:25:04.481821Z



usage:
utcnow [values ...] | default output in rfc3339 format
utcnow --unixtime [values ...] | short: -u output as unixtime
utcnow --diff <from> <to> | short: -d diff in seconds: from -> to

help:
utcnow --help | short: -h display this message
utcnow --version | short: -v installed version (0.3.3)