Metadata-Version: 2.4
Name: atomic-counter
Version: 0.1.4
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: bump-my-version ; extra == 'develop'
Requires-Dist: check-manifest ; extra == 'develop'
Requires-Dist: cibuildwheel ; extra == 'develop'
Requires-Dist: maturin >=1.1, <2 ; extra == 'develop'
Requires-Dist: pytest ; extra == 'develop'
Requires-Dist: pytest-cov ; extra == 'develop'
Requires-Dist: ruff ; extra == 'develop'
Requires-Dist: twine ; extra == 'develop'
Requires-Dist: wheel ; extra == 'develop'
Provides-Extra: develop
License-File: LICENSE
Summary: Atomic Counters
Author: Tim Paine
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: repository, https://github.com/timkpaine/atomic-counter
Project-URL: homepage, https://github.com/timkpaine/atomic-counter

# Atomic Counter

[![Build Status](https://github.com/timkpaine/atomic-counter/workflows/Build%20Status/badge.svg?branch=main)](https://github.com/timkpaine/atomic-counter/actions?query=workflow%3A%22Build+Status%22)
[![Coverage](https://codecov.io/gh/timkpaine/atomic-counter/branch/main/graph/badge.svg)](https://codecov.io/gh/timkpaine/atomic-counter)
[![License](https://img.shields.io/github/license/timkpaine/atomic-counter.svg)](https://pypi.python.org/pypi/atomic-counter)
[![PyPI](https://img.shields.io/pypi/v/atomic-counter.svg)](https://pypi.python.org/pypi/atomic-counter)

## Overview
`atomic-counter` is a rust library for generating a monotonically increasing sequence of integers. Depending on the particular configuration of the counter, the generated sequence will be produce unique numbers down to the nanosecond, regardless of memory state.
E.g. if you quit the process and recreate a new counter `>1ns` later, your sequence is guaranteed to still be monotonically increasing (but with a gap).

## Usage

```python
from atomic_counter import Counter

c = Counter(base_in_nanos)

c.next()  # generate next number in sequence
```

To create e.g. a daily counter, pass in `base=today in nanos`. As this is a common occurrence for sequences that reset daily, a convenience function `def daily() -> Counter:` is provided.


There is also a `TimeCounter` class provided. A 64 bit unsigned integer is created that is monotonically increasing, and allows for converting to microseconds to serve as a timestamp (up to the year 2112). Will break if more than 4096 calls to "next" are called within a single microsecond (which is almost assuredly never going to be physically possible, every call makes a system call to get the current time).

```python
from atomic_counter import TimeCounter
from datetime import datetime, timezone

c = TimeCounter()

x = c.next()  # generate id
x_time = TimeCounter.to_datetime(x)  # generates the datetime where the value was called.
now = datetime.now(timezone.utc)
assert x_time <= now
```
