userharbor-inmemory 0.1.0

A minimal, contract-tested UserStore implementation and GitHub template for building custom UserHarbor storage integrations.

userharbor-inmemory is a minimal, contract-tested UserStore implementation for UserHarbor. It can be installed directly for tests and examples or used as a GitHub template when building a custom storage integration.

[!WARNING] All data is process-local and is lost when the store instance is discarded. This package is not a persistent database and is not intended for production storage.

Installation

pip install userharbor-inmemory

The package depends on userharbor and has no database or framework dependencies.

Usage

from userharbor import UserHarbor
from userharbor_inmemory import InMemoryUserStore


store = InMemoryUserStore()

harbor = UserHarbor(
    secret_key="your-secret-key",
    store=store,
    email_sender=email_sender,
)

Each InMemoryUserStore instance starts empty and keeps its data for the lifetime of that instance.

The store implements the complete UserHarbor persistence contract:

• users and password hashes
• email verification and password reset tokens
• sessions and session refresh
• roles and permissions
• user-role and role-permission assignments
• commit, rollback, and nested transaction behavior

Each user has at most one active email verification token and one active password reset token. Storing a replacement invalidates the previous token. Users may have multiple active sessions.

Use as an integration template

Select Use this template on GitHub and create a new repository. The generated repository starts with a complete implementation and a passing contract suite, so backend code can be replaced incrementally while the tests continue to verify UserStore behavior.

GitHub copies files without replacing project-specific names. After creating a repository:

1. Rename the distribution in pyproject.toml.
2. Rename the userharbor_inmemory package and InMemoryUserStore class.
3. Update project metadata, links, badges, and this README.
4. Replace the in-memory dictionaries and snapshot transaction with the target backend.
5. Adapt the user_store fixture in tests/conftest.py to create and clean up the backend.
6. Keep backend-specific tests separate from the shared contract suite.
7. Run the complete test suite before publishing.

The contract tests stay intentionally small in this repository:

# tests/test_user_store_contract.py

from userharbor.testing.user_store_contract import *  # noqa: F403

# tests/conftest.py

import pytest

from userharbor_inmemory import InMemoryUserStore


@pytest.fixture
def user_store() -> InMemoryUserStore:
    return InMemoryUserStore()

See the UserStore contract testing guide and custom integrations guide for the complete behavioral requirements.

Development

Install the project and run its tests:

uv sync
uv run pytest

The suite imports the shared contract distributed with UserHarbor. Tests specific to this package remain in tests/test_public_api.py.

To develop against an unpublished local UserHarbor checkout, keep both repositories in the same parent directory and run:

uv run --with-editable ../userharbor pytest

Limitations

InMemoryUserStore is deliberately small. It does not provide persistence across process restarts, cross-process sharing, durable transactions, or concurrency guarantees. Its snapshot-based transaction implementation exists to reproduce the atomic behavior required by UserHarbor in tests and examples.

License

UserHarbor In-Memory is licensed under the MIT License. See LICENSE for details.