python-ulid 3.1.0__tar.gz → 4.0.0__tar.gz

python_ulid-4.0.0/.envrc

@@ -0,0 +1 @@
+use flox

python_ulid-4.0.0/.github/workflows/lint-and-test.yml

@@ -0,0 +1,101 @@
+name: lint-and-test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          python-version: "3.14"
+      - name: Lint documentation
+        run: uv run doc8 docs/source
+
+  lint-code:
+    runs-on: ubuntu-latest
+    name: Lint code
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          python-version: "3.14"
+      - name: Lint style
+        run: uv run ruff check
+
+  lint-typing:
+    runs-on: ubuntu-latest
+    name: Lint type annotations
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          python-version: "3.14"
+      - name: Lint typing
+        run: uv run poe check-types
+
+  test:
+    runs-on: ubuntu-latest
+    name: Run tests
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Test
+        run: uv run poe test
+
+      - name: Upload coverage data
+        uses: actions/upload-artifact@v7
+        with:
+          include-hidden-files: true
+          name: coverage-${{ matrix.python-version }}
+          path: .coverage*
+
+
+  coverage:
+    runs-on: ubuntu-latest
+    name: Report coverage
+    needs:
+      - test
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+
+      - name: Download coverage data
+        uses: actions/download-artifact@v8
+        with:
+          pattern: coverage-*
+          merge-multiple: true
+
+      - name: Combine coverage data
+        run: uv run poe cov-combine
+
+      - name: Export coverage reports
+        run: uv run poe cov-xml
+
+      - uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+
+  package:
+    name: Build & verify package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: hynek/build-and-inspect-python-package@v2

python_ulid-4.0.0/.github/workflows/publish.yml

@@ -0,0 +1,23 @@
+name: publish
+
+on:
+  push:
+    tags: ["*"]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          python-version: "3.14"
+      - name: Build
+        run: uv build
+      - name: Publish
+        env:
+          UV_PUBLISH_USERNAME: ${{ secrets.PYPI_USERNAME }}
+          UV_PUBLISH_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
+        run: uv publish

{python_ulid-3.1.0 → python_ulid-4.0.0}/.gitignore

@@ -4,12 +4,12 @@ __pycache__
 
 /.tox
 /.coverage
+/.coverage.*
 /.cache
 /.eggs
 /.mypy_cache
 /.pytest_cache
 /.ruff_cache
-/.devbox
 
 /coverage.xml
 /dist/

python_ulid-4.0.0/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.4
+    hooks:
+      - id: ruff-check
+      - id: ruff-format
+  - repo: https://github.com/pycqa/doc8
+    rev: v2.0.0
+    hooks:
+      - id: doc8
+  - repo: local
+    hooks:
+      - id: pyrefly-check
+        name: pyrefly
+        entry: uv run pyrefly check
+        language: system
+        types: [python]
+        pass_filenames: false

python_ulid-4.0.0/AGENTS.md

@@ -0,0 +1,89 @@
+# Guidelines for AI Coding Agents
+
+Welcome! If you are an AI assistant, coding agent, or language model (e.g., Antigravity, Claude Code, Cursor, Copilot) helping to develop `python-ulid`, please adhere to the guidelines in this document.
+
+These instructions ensure consistency, prevent common development errors, and keep code quality aligned with the project's standards.
+
+---
+
+## 🏗️ Project Stack & Tooling
+
+We use modern, fast, and strict tooling for Python development. Always use the specified commands below.
+
+- **Dependency Manager**: We use **[uv](https://github.com/astral-sh/uv)**.
+  - Do *not* use raw `pip`, `poetry`, or `pdm`.
+  - To install dependencies, run: `uv sync`.
+  - Always prefix commands with `uv run` to execute them in the correct environment (e.g., `uv run pytest`).
+- **Task Runner**: We use **[Poe the Poet](https://github.com/nat-n/poethepoet)**.
+  - Development tasks are defined in `pyproject.toml` under `[tool.poe.tasks]`.
+  - Run checks with `uv run poe check`.
+- **Linting & Formatting**: We use **[Ruff](https://github.com/astral-sh/ruff)**.
+  - Standard line-length limit is **100 characters**.
+  - Auto-format code using `uv run poe fmt`.
+- **Static Typing**: We use **[pyrefly](https://github.com/mdomke/pyrefly)** for strict static analysis.
+  - Run type checking using `uv run poe check-types`.
+
+---
+
+## 🎯 Coding Standards for Agents
+
+### 1. Mandatory Type Annotations
+We require full, strict type annotations across the entire codebase.
+- **Rules**:
+  - Always annotate all function parameters and return values.
+  - Avoid `Any` where possible; use specific types, unions, or generics.
+  - Run type checking to verify compliance: `uv run poe check-types`.
+
+### 2. Ruff Compliance
+- **Formatting**: Run formatting before finalizing any file modifications.
+  - Use `uv run poe fmt` to auto-format.
+  - Code style rules are detailed in `pyproject.toml` and `.ruff_defaults.toml`.
+- **Imports**: We use single-line imports and specific import order (`isort` rules). Let Ruff handle this automatically.
+
+### 3. Production-Ready Code Only
+- Never generate code with comments like `# TODO: implement this`, `# placeholder`, or partial code blocks.
+- Implement the full logic requested, ensuring error handling and correct edge cases are covered.
+
+---
+
+## 📝 Changelog
+
+We maintain a human-readable changelog in [CHANGELOG.rst](file:///Users/martin.domke/Source/private/ulid/CHANGELOG.rst) following the **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/)** conventions.
+
+- **Section headings**: Group entries under the standard headings, in this order: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`. Omit any section that has no entries.
+- **Removals belong under `Removed`**: Do *not* fold removed or renamed public APIs into `Changed`.
+- **Versioning**: Follow [Semantic Versioning](https://semver.org). A breaking change (e.g. a removed public API) requires a **major** version bump and a `.. warning::` admonition describing the migration path.
+- **Entry format**: Each release has a ``` `X.Y.Z`_ - YYYY-MM-DD ``` heading plus a matching compare link at the bottom of the file (``.. _X.Y.Z: https://github.com/mdomke/python-ulid/compare/PREV...X.Y.Z``).
+- **reStructuredText**: Keep lines within **100 characters** (enforced by `doc8`) and reference public symbols with Sphinx roles such as `:class:` and `:meth:` — the changelog is included into the rendered documentation.
+
+---
+
+## 🛠️ Verification Workflow
+
+Before completing any task, you **MUST** run the verification commands to ensure no regressions or style issues are introduced.
+
+1. **Format Code**:
+   ```bash
+   uv run poe fmt
+   ```
+2. **Run Lints, Types & Style Checks**:
+   ```bash
+   uv run poe check
+   ```
+3. **Run Test Suite**:
+   ```bash
+   uv run poe test
+   ```
+
+Make sure all checks pass without errors.
+
+---
+
+## 📂 Codebase Navigation
+
+- **`/ulid`**: Contains the source code of the `python-ulid` package.
+- **`/tests`**: Contains all unit and integration tests. Write corresponding test cases here for any new logic.
+- **`/docs`**: Contains Sphinx-based documentation.
+- **`pyproject.toml`**: The single source of truth for dependencies, tools configuration, and Poe tasks.
+
+Refer to the primary developer documentation and [CONTRIBUTING.md](file:///Users/martin.domke/Source/private/ulid/CONTRIBUTING.md) for more details.

{python_ulid-3.1.0 → python_ulid-4.0.0}/CHANGELOG.rst

@@ -5,6 +5,67 @@ Changelog
 
 Versions follow `Semantic Versioning <http://www.semver.org>`_
 
+`4.0.0`_ - 2026-07-20
+---------------------
+
+.. warning::
+
+   **Breaking change:** the ``ValueProvider`` class and the ``ULID.provider`` class attribute
+   have been removed. ULID generation is now handled by the new :class:`.ULIDGenerator` together
+   with pluggable monotonicity policies. To customize generation, construct a
+   :class:`.ULIDGenerator` (optionally with a custom clock, randomness source, or policy) and
+   either call its ``generate()`` method or assign it to ``ulid.default_generator``.
+
+Added
+~~~~~
+* Added a public :class:`.ULIDGenerator` class that encapsulates ULID generation and can be
+  configured with a custom clock, randomness source, and monotonicity policy.
+* Added pluggable monotonicity policies: :class:`.StrictMonotonicPolicy` (the default),
+  :class:`.LaxMonotonicPolicy` and :class:`.PureRandomPolicy`, together with the
+  :class:`.MonotonicityPolicy` protocol and the :class:`.BaseMonotonicPolicy` base class for
+  implementing custom policies.
+* Added a module-level ``ulid.default_generator`` that can be reassigned to route ``ULID()`` and
+  the ``ULID.from_*`` constructors through a custom :class:`.ULIDGenerator`.
+
+Removed
+~~~~~~~
+* Removed the ``ValueProvider`` class and the ``ULID.provider`` attribute in favour of
+  :class:`.ULIDGenerator` and the monotonicity policies. Code that replaced ``ULID.provider`` or
+  subclassed ``ValueProvider`` must migrate to a custom :class:`.ULIDGenerator` assigned to
+  ``ulid.default_generator``.
+* Removed the internal ``validate_type`` decorator. The ``ULID.from_*`` constructors still raise
+  ``TypeError`` for arguments of the wrong type, so runtime behaviour is unchanged.
+
+`3.2.1`_ - 2026-07-17
+---------------------
+Fixed
+~~~~~
+* Corrected the build and publish pipeline and the generated source distribution. This release
+  contains no changes to the library code.
+
+`3.2.0`_ - 2026-07-17
+---------------------
+Added
+~~~~~
+* Added transparent bidirectional UUIDv7 conversion methods (``ULID.to_uuid7`` and
+  ``ULID.from_uuidv7``) `@pirate <https://github.com/pirate>`_.
+* Added a ``--uuid7`` option to the CLI's ``show`` command to convert and output a ULID as an
+  RFC 4122 compliant UUIDv7.
+
+Changed
+~~~~~~~
+* Dropped support for Python 3.9 and added support for Python 3.14
+  `@Avihais12344 <https://github.com/Avihais12344>`_.
+* Depend on ``typing-extensions`` only when running on Python < 3.11 `@musicinmybrain <https://github.com/musicinmybrain>`_.
+* Migrated package and development workflow from Hatch to ``uv`` and ``poethepoet``.
+* Configured Flox for bootstrapping the development environment.
+
+Fixed
+~~~~~
+* Fixed a clock-skew bug where non-monotonic ULIDs could be generated when crossing a millisecond boundary between timestamp and randomness sampling `@gaoflow <https://github.com/gaoflow>`_.
+* Fixed warning from ``uv`` during synchronization `@jaseemabid <https://github.com/jaseemabid>`_.
+* Resolved various Ruff linter warnings and Pyrefly type checker issues.
+
 `3.1.0`_ - 2025-08-18
 ---------------------
 Changed
@@ -197,6 +258,9 @@ Changed
 * The package now has no external dependencies.
 * The test-coverage has been raised to 100%.
 
+.. _4.0.0: https://github.com/mdomke/python-ulid/compare/3.2.1...4.0.0
+.. _3.2.1: https://github.com/mdomke/python-ulid/compare/3.2.0...3.2.1
+.. _3.2.0: https://github.com/mdomke/python-ulid/compare/3.1.0...3.2.0
 .. _3.1.0: https://github.com/mdomke/python-ulid/compare/3.0.0...3.1.0
 .. _3.0.0: https://github.com/mdomke/python-ulid/compare/2.7.0...3.0.0
 .. _2.7.0: https://github.com/mdomke/python-ulid/compare/2.6.0...2.7.0

python_ulid-4.0.0/CONTEXT.md

@@ -0,0 +1,34 @@
+# Domain Glossary & Context: python-ulid
+
+Welcome to the architectural domain reference for the `python-ulid` project. This document outlines the ubiquitous language, core domain entities, and structural concepts of this implementation.
+
+---
+
+## Core Concepts & Vocabulary
+
+### ULID
+*   **Definition**: A Universally Unique Lexicographically Sortable Identifier.
+*   **Format**: A 128-bit value consisting of:
+    *   **Timestamp**: 48 bits, representing epoch time in milliseconds.
+    *   **Randomness**: 80 bits, representing high-entropy random generation.
+*   **Representation**: Encoded as a 26-character Base32 string.
+*   **Nature**: Act as an immutable, hashable **Value Object**.
+
+### ULIDGenerator
+*   **Definition**: A deep, stateful generator responsible for orchestrating the creation of new `ULID` identifiers.
+*   **Responsibilities**:
+    *   Sampling system or injected clocks for the **Timestamp**.
+    *   Sourcing entropy for the **Randomness**.
+    *   Tracking state and enforcing **Monotonicity** rules.
+    *   Guaranteeing thread-safe generation across execution contexts.
+
+### Monotonicity & Policies
+*   **Definition**: The deterministic ordering property where multiple ULID instances generated within the exact same millisecond resolve their randomness component to prevent sorting collisions.
+*   **MonotonicityPolicy**: An extensible interface (seam) for configuring generator behavior:
+    *   **StrictMonotonicPolicy**: Always increments the randomness by 1 under same-millisecond collisions, raising an overflow error if randomness is exhausted.
+    *   **PureRandomPolicy**: Ignores previous states and always generates fresh random bytes, maximizing security and entropy.
+    *   **LaxMonotonicPolicy**: Increments monotonically, but on same-millisecond randomness exhaustion, regenerates fresh randomness instead of raising an error or sleeping.
+
+### Base32 Engine
+*   **Definition**: Crockford's Base32 translation layer.
+*   **Nature**: Encodes/decodes binary representation using a restricted alphabet of 32 characters (`0123456789ABCDEFGHJKMNPQRSTVWXYZ`), omitting ambiguous characters like `I`, `L`, `O`, and `U` to guarantee maximum readability.

python_ulid-4.0.0/CONTRIBUTING.md

@@ -0,0 +1,146 @@
+# Contributing to python-ulid
+
+Thank you for your interest in contributing to `python-ulid`! We appreciate all kinds of contributions: fixing bugs, improving documentation, submitting feature requests, or writing code.
+
+This document guides you through setting up your local environment and details our development workflow and coding standards.
+
+---
+
+## 🚀 Getting Started
+
+We support two ways to set up your local development environment: **Flox** (recommended, zero-configuration setup) or a **Manual** setup.
+
+### Option 1: Using Flox (Recommended)
+
+If you have [Flox](https://flox.dev/) installed, setting up your environment is completely automated. Flox will automatically handle installing `uv`, Python, project dependencies, and pre-commit hooks inside a reproducible environment.
+
+1. **Fork and clone** the repository:
+   ```bash
+   git clone https://github.com/<your-username>/python-ulid.git
+   cd python-ulid
+   ```
+
+2. **Activate the Flox environment**:
+   ```bash
+   flox activate
+   ```
+   That's it! Flox automatically sets up everything for you and activates your python virtual environment.
+
+---
+
+### Option 2: Manual Setup
+
+If Flox is not an option, you can set up your environment manually. We use [uv](https://github.com/astral-sh/uv) for fast, robust package and dependency management.
+
+1. **Prerequisites**:
+   - **Python**: `>= 3.10`
+   - **uv**: Install via `curl -LsSf https://astral.sh/uv/install.sh | sh` (or your preferred package manager)
+
+2. **Fork and clone** the repository:
+   ```bash
+   git clone https://github.com/<your-username>/python-ulid.git
+   cd python-ulid
+   ```
+
+3. **Sync the dependencies**:
+   This will automatically create a `.venv` virtual environment and install all packages in the developer and documentation groups:
+   ```bash
+   uv sync
+   ```
+
+4. **Install pre-commit hooks**:
+   We use `prek` (a fast, Rust-based alternative to pre-commit) to manage our Git hooks, ensuring code style, formatting, and static typing checks run automatically before each commit.
+   ```bash
+   uv run prek install
+   ```
+
+---
+
+## 🛠️ Development Tasks & Commands
+
+We use [Poe the Poet](https://github.com/nat-n/poethepoet) as our task runner. Depending on how you set up your development environment, you can invoke the tasks directly or via `uv run`:
+
+- **With Flox (Recommended)**: Since the virtual environment is automatically activated in your shell, you can run all commands directly:
+  ```bash
+  poe test
+  ```
+- **With Manual Setup**: If you did not use Flox, prefix all tasks with `uv run`:
+  ```bash
+  uv run poe test
+  ```
+  (You can also manually activate the virtual environment to get the same shorthands as above).
+
+### Common Development Tasks
+
+| Task | Command (Flox) | Command (Manual) | Description |
+| :--- | :--- | :--- | :--- |
+| **All Checks** | `poe check` | `uv run poe check` | Run linter, formatter checks, type checking, and docs check. |
+| **Formatting** | `poe fmt` | `uv run poe fmt` | Auto-format Python source files using `ruff format`. |
+| **Lint** | `poe check-code` | `uv run poe check-code` | Check source files for lint and code style issues using `ruff`. |
+| **Format Check** | `poe check-fmt` | `uv run poe check-fmt` | Dry-run format check without modifying files. |
+| **Type Check** | `poe check-types` | `uv run poe check-types` | Run strict static analysis and type verification with `pyrefly`. |
+| **Docs Lint** | `poe check-docs` | `uv run poe check-docs` | Lint documentation style using `doc8`. |
+| **Run Tests** | `poe test` | `uv run poe test` | Run pytest with code coverage tracking. |
+| **Build Docs** | `poe docs` | `uv run poe docs` | Build the HTML documentation locally using Sphinx. |
+
+> [!TIP]
+> Before pushing any changes or opening a Pull Request, always make sure to run the complete checks suite with **`poe check`** (or `uv run poe check`) and run the test suite with **`poe test`** (or `uv run poe test`).
+
+### Manual Hook Execution with prek
+
+If you want to run all checks against your staged or unstaged files manually:
+
+- **With Flox**:
+  ```bash
+  prek run --all-files
+  ```
+- **With Manual Setup**:
+  ```bash
+  uv run prek run --all-files
+  ```
+
+---
+
+## 🎨 Coding Standards
+
+To maintain a clean, readable, and highly maintainable codebase, we enforce the following development standards:
+
+### 1. Type Annotations
+- **Strictly Required**: We enforce type annotations across the entire codebase. This includes all function signatures, arguments, and return types.
+- **Static Analysis**: Our configuration has `disallow_untyped_defs = true` set for Mypy and uses strict `pyrefly` checks. Untyped or partially-typed code will fail the lint pipelines.
+- **Example**:
+  ```python
+  def generate_ulid(timestamp: float | None = None) -> ULID:
+      ...
+  ```
+
+### 2. Ruff Formatting & Linting
+- **Formatting**: We use [Ruff](https://github.com/astral-sh/ruff) for automatic code formatting (`ruff format`).
+- **Code Style**: Ruff also handles our lint checks, including import sorting (`isort`), code complexity limits (`mccabe`), and code style conventions.
+- **Configuration**:
+  - Line length limit: **100 characters**.
+  - Imports are forced to single lines and ordered.
+  - Standard Ruff defaults apply (see `.ruff_defaults.toml`).
+
+---
+
+## 📬 Submitting a Pull Request
+
+1. **Create a branch** for your feature or bugfix:
+   ```bash
+   git checkout -b feature/my-cool-improvement
+   ```
+2. **Make your changes**, ensuring you write comprehensive unit tests.
+3. **Format and verify** your code (e.g. using `poe` directly if using Flox, or prefixed with `uv run` if manual):
+   ```bash
+   poe fmt
+   poe check
+   poe test
+   ```
+4. **Commit your changes**:
+   Our pre-commit hooks will automatically trigger to verify your work.
+5. **Push and open a PR** on GitHub! Please provide a descriptive title and detailed explanation of your changes in the PR description.
+
+---
+
+Thank you for helping make `python-ulid` better! 🌟

{python_ulid-3.1.0 → python_ulid-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-ulid
-Version: 3.1.0
+Version: 4.0.0
 Summary: Universally unique lexicographically sortable identifier
 Project-URL: Homepage, https://github.com/mdomke/python-ulid
 Project-URL: Documentation, https://python-ulid.readthedocs.io
@@ -18,13 +18,14 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: MacOS :: MacOS X
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries
-Requires-Python: >=3.9
+Requires-Python: >=3.10
+Requires-Dist: typing-extensions; python_version < '3.11'
 Provides-Extra: pydantic
 Requires-Dist: pydantic>=2.0; extra == 'pydantic'
 Description-Content-Type: text/x-rst
@@ -40,6 +41,7 @@ A ``ULID`` is a *universally unique lexicographically sortable identifier*. It i
 * Uses Crockford's base32 for better efficiency and readability (5 bits per character)
 * Case insensitive
 * No special characters (URL safe)
+* Monotonic sort order (correctly detects and handles the same millisecond)
 
 In general the structure of a ULID is as follows:
 
@@ -148,6 +150,78 @@ The ``ULID`` class can be directly used for the popular data validation library
 
 .. pydantic-end
 
+.. monotonic-begin
+
+Monotonic Support
+-----------------
+
+This library by default supports the implementation for monotonic sort order suggested by the
+official ULID specification.
+
+This means that ULID values generated in the same millisecond will have linear increasing randomness
+values. If :math:`r_1` and :math:`r_2` are the randomness values of two ULIDs with the same
+timestamp, then :math:`r_2 = r_1 + 1`.
+
+.. monotonic-end
+
+.. generators-begin
+
+Generators and policies
+-----------------------
+
+Every ``ULID`` is produced by a ``ULIDGenerator``, which samples a clock for the timestamp,
+sources entropy for the randomness, and enforces a *monotonicity policy*. The bare ``ULID()``
+constructor and the ``ULID.from_*`` factory methods delegate to a shared module-level
+``default_generator``.
+
+For most use cases the default is all you need. To customize generation — a different clock, a
+custom entropy source, or another monotonicity policy — create your own ``ULIDGenerator`` and
+call ``generate()``
+
+.. code-block:: pycon
+
+   >>> from ulid import ULIDGenerator
+   >>> generator = ULIDGenerator()
+   >>> generator.generate()
+   ULID(01HB0N8Q4RCE7YB1M2VZK9WX3T)
+
+Choosing a monotonicity policy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A policy decides how the randomness is resolved when multiple ULIDs are generated within the same
+millisecond. Three policies are available:
+
+* ``StrictMonotonicPolicy`` *(default)* — increments the randomness by 1 on a same-millisecond
+  collision and raises ``ValueError`` if the randomness is exhausted. This is the behaviour
+  described under `Monotonic Support`_.
+* ``LaxMonotonicPolicy`` — increments like the strict policy, but regenerates fresh randomness
+  instead of raising when the randomness is exhausted.
+* ``PureRandomPolicy`` — ignores previous state and always draws fresh randomness, maximizing
+  entropy at the cost of same-millisecond sort order.
+
+.. code-block:: pycon
+
+   >>> from ulid import ULIDGenerator, PureRandomPolicy
+   >>> generator = ULIDGenerator(policy=PureRandomPolicy())
+   >>> generator.generate()
+   ULID(01HB0N9F3TA5KDQ6ZE0WYV7MRC)
+
+Overriding the default generator
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To make ``ULID()`` and the ``ULID.from_*`` constructors use a custom generator globally, reassign
+``ulid.default_generator``
+
+.. code-block:: pycon
+
+   >>> import ulid
+   >>> from ulid import ULID, ULIDGenerator, LaxMonotonicPolicy
+   >>> ulid.default_generator = ULIDGenerator(policy=LaxMonotonicPolicy())
+   >>> ULID()  # now generated with the lax policy
+   ULID(01HB0NB7X2M4C8VKQ0ZF5WD9RA)
+
+.. generators-end
+
 .. cli-begin
 
 Command line interface
@@ -205,3 +279,9 @@ Other implementations
 * `ulid/javascript <https://github.com/ulid/javascript>`_
 * `RobThree/NUlid <https://github.com/RobThree/NUlid>`_
 * `imdario/go-ulid <https://github.com/imdario/go-ulid>`_
+
+Contributions
+-------------
+
+Contributions are welcome! Feel free to create pull-requests for issues or feature requests.
+It might be worth creating an issue upfront to discuss the matter.