ahawker / ulid

Universally Unique Lexicographically Sortable Identifier (ULID) in Python 3
Apache License 2.0
695 stars 42 forks source link

Add monotonic randomness support #473

Closed ahawker closed 4 years ago

ahawker commented 4 years ago

Doing this required a refactoring of how timestamp/randomness values were generated. We've broken these into "provider" implementations with the "default" provider being the implementation that exists today, e.g. randomness values are random even on identical timestamp values.

A "monotonic" provider has been added which monotonically increments the first randomness value on timestamp collision until an overflow.

Additionally, the API has been broken out into a subpackage so we can stay agnostic to the provider and just plug it in. Work has been done to maintain the existing package interface for backwards compatibility.

This implementation should conform to the monotonic implementation found in https://github.com/ulid/spec even though there is discussion/concerns about it. See: https://github.com/ulid/spec/issues/40, https://github.com/ulid/spec/issues/11, https://github.com/ulid/javascript/issues/74

Status: Ready

If merged, this PR fixes #306.

TODO:

Usage:

>>> import ulid
>>> ulid.new()
<ULID('01EFZ5YBXG4G619GDRWESKW04C')>
>>> from ulid import monotonic as ulid
>>> ulid.new()
<ULID('01EFZ5YJ74PE8284B5M74CZBVW')>
>>> import time
>>> ts = time.time()
>>> ulid.from_timestamp(ts)
<ULID('01EFZ62V7VTEQR4Q788PSBBQP8')>
>>> ulid.from_timestamp(ts)
<ULID('01EFZ62V7VTEQR4Q788PSBBQP9')>
>>> ulid.from_timestamp(ts)
<ULID('01EFZ62V7VTEQR4Q788PSBBQPA')>
>>> ulid.from_timestamp(ts)
<ULID('01EFZ62V7VTEQR4Q788PSBBQPB')>
>>> ulid.from_timestamp(time.time())
<ULID('01EFZ648ZWCY8FEVYTN1YKBZXG')>
codecov[bot] commented 4 years ago

Codecov Report

Merging #473 into master will not change coverage. The diff coverage is 100.00%.

Impacted file tree graph

@@            Coverage Diff            @@
##            master      #473   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            6        13    +7     
  Lines          368       467   +99     
  Branches        77        79    +2     
=========================================
+ Hits           368       467   +99     
Impacted Files Coverage Δ
ulid/api/__init__.py 100.00% <100.00%> (ø)
ulid/api/api.py 100.00% <100.00%> (ø)
ulid/api/default.py 100.00% <100.00%> (ø)
ulid/api/monotonic.py 100.00% <100.00%> (ø)
ulid/consts.py 100.00% <100.00%> (ø)
ulid/hints.py 100.00% <100.00%> (ø)
ulid/providers/__init__.py 100.00% <100.00%> (ø)
ulid/providers/base.py 100.00% <100.00%> (ø)
ulid/providers/default.py 100.00% <100.00%> (ø)
ulid/providers/monotonic.py 100.00% <100.00%> (ø)
... and 9 more

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 888b087...7ce680a. Read the comment docs.