regstack 0.2.2__tar.gz → 0.2.4__tar.gz

{regstack-0.2.2 → regstack-0.2.4}/CHANGELOG.md

@@ -5,6 +5,35 @@ authoritative copy lives at
 [`docs/changelog.md`](docs/changelog.md) and is rendered into the
 Sphinx docs.
 
+## 0.2.4 — 2026-04-28
+
+**Breaking** — back-compat shims removed:
+
+- `RegStack.install_indexes()` (alias for `install_schema()`).
+- `ObjectIdStr` alias for `IdStr` in `regstack.models._objectid`.
+- Re-exports of `UserAlreadyExistsError`,
+  `PendingAlreadyExistsError`, `MfaVerifyOutcome`, and
+  `MfaVerifyResult` from `regstack.backends.mongo.repositories.*`.
+  Their canonical home is `regstack.backends.protocols`.
+
+If you import any of these from the old paths, switch to:
+- `RegStack.install_schema()`
+- `from regstack.models._objectid import IdStr`
+- `from regstack.backends.protocols import UserAlreadyExistsError`
+  (and friends).
+
+The internal mongo `install_indexes(db, config)` function is unchanged.
+
+## 0.2.3 — 2026-04-28
+
+Docs-only release. Restructured the API reference around the current
+package layout (post multi-backend refactor) and added Google-style
+docstrings (Args / Returns / Raises) to the public surface — RegStack,
+JwtCodec, PasswordHasher, LockoutService, AuthDependencies,
+HookRegistry, EmailService, SmsService, the router builders, and the
+Clock implementations. Dataclass field docs moved to PEP 258
+attribute docstrings. Sphinx builds clean under `-W` again.
+
 ## 0.2.2 — 2026-04-28
 
 Docs-only release. The README and Sphinx docs landing page now lead

{regstack-0.2.2 → regstack-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: regstack
-Version: 0.2.2
+Version: 0.2.4
 Summary: Embeddable user registration, login, and account management for FastAPI apps. SQLite / Postgres / MongoDB.
 Project-URL: Homepage, https://github.com/jdrumgoole/regstack
 Project-URL: Repository, https://github.com/jdrumgoole/regstack

regstack-0.2.4/docs/api.md

@@ -0,0 +1,278 @@
+# API reference
+
+Auto-generated from docstrings. The most useful entry point is
+[`regstack.RegStack`](#regstack.app.RegStack); everything else hangs
+off it.
+
+This page is organized by what you'd reach for, not by package
+hierarchy. Each section starts with a one-paragraph orientation,
+then the ``autoclass`` / ``autofunction`` directives pull the
+docstrings, signatures, and parameter docs straight off the package
+source.
+
+## Top-level
+
+The handful of things you import from `regstack` directly:
+
+- [`RegStack`](#regstack.app.RegStack) — the embeddable façade.
+- [`RegStackConfig`](#regstack.config.schema.RegStackConfig) — top-level config.
+- [`EmailConfig`](#regstack.config.schema.EmailConfig) — email-backend sub-config.
+- [`SmsConfig`](#regstack.config.schema.SmsConfig) — SMS-backend sub-config.
+
+Most embeddings need only `RegStack` and `RegStackConfig`.
+
+## Façade
+
+`RegStack` is the embeddable façade. One per FastAPI application;
+hosts mount its `router` and (optionally) `ui_router`. All collaborators
+— password hasher, JWT codec, repos, hooks bus, email and SMS
+services — hang off the instance.
+
+```{eval-rst}
+.. autoclass:: regstack.app.RegStack
+   :members:
+   :show-inheritance:
+```
+
+## Configuration
+
+`RegStackConfig` is a `pydantic-settings` model loaded from
+environment variables (`REGSTACK_*`), an optional
+`regstack.secrets.env`, an optional `regstack.toml`, and programmatic
+kwargs — in that priority order. See the
+[Configuration guide](configuration.md) for every field with its
+default.
+
+```{eval-rst}
+.. autoclass:: regstack.config.schema.RegStackConfig
+   :members:
+   :show-inheritance:
+   :exclude-members: model_config, model_fields, model_computed_fields
+
+.. autoclass:: regstack.config.schema.EmailConfig
+   :members:
+   :show-inheritance:
+   :exclude-members: model_config, model_fields, model_computed_fields
+
+.. autoclass:: regstack.config.schema.SmsConfig
+   :members:
+   :show-inheritance:
+   :exclude-members: model_config, model_fields, model_computed_fields
+
+.. autofunction:: regstack.config.loader.load_config
+```
+
+## Auth primitives
+
+The pieces that make authentication work: password hashing (Argon2id),
+JWT issuance and validation with per-purpose derived keys, login
+lockout, and the FastAPI dependency factory. Hosts rarely instantiate
+these directly — they're built and wired by the `RegStack` constructor
+— but the docstrings on the public methods explain the contract.
+
+```{eval-rst}
+.. autoclass:: regstack.auth.password.PasswordHasher
+   :members:
+
+.. autoclass:: regstack.auth.jwt.JwtCodec
+   :members:
+
+.. autoclass:: regstack.auth.jwt.TokenPayload
+   :members:
+
+.. autoexception:: regstack.auth.jwt.TokenError
+
+.. autofunction:: regstack.auth.jwt.is_payload_bulk_revoked
+
+.. autoclass:: regstack.auth.lockout.LockoutService
+   :members:
+
+.. autoclass:: regstack.auth.lockout.LockoutDecision
+   :members:
+
+.. autoclass:: regstack.auth.dependencies.AuthDependencies
+   :members:
+```
+
+### Time
+
+Every time-sensitive operation reads `now()` through a `Clock`. Tests
+inject `FrozenClock` to make assertions deterministic.
+
+```{eval-rst}
+.. autoclass:: regstack.auth.clock.Clock
+   :members:
+
+.. autoclass:: regstack.auth.clock.SystemClock
+   :members:
+
+.. autoclass:: regstack.auth.clock.FrozenClock
+   :members:
+```
+
+## Backends
+
+regstack ships three storage backends behind one set of `Protocol`
+classes: SQLite (default, no infrastructure), PostgreSQL, and MongoDB.
+The active backend is auto-built from `config.database_url`'s URL
+scheme via `build_backend`. Hosts that need to share a connection pool
+with their own application can pass an explicit `Backend` to the
+`RegStack` constructor.
+
+```{eval-rst}
+.. autoclass:: regstack.backends.base.Backend
+   :members:
+   :show-inheritance:
+
+.. autoclass:: regstack.backends.base.BackendKind
+   :members:
+
+.. autofunction:: regstack.backends.factory.build_backend
+
+.. autoclass:: regstack.backends.mongo.MongoBackend
+   :members:
+   :show-inheritance:
+
+.. autoclass:: regstack.backends.sql.SqlBackend
+   :members:
+   :show-inheritance:
+```
+
+### Repository protocols
+
+The five repository protocols are the contract every backend
+implements. Routers and services depend only on these — switching
+backends is a wiring change, not a code change.
+
+```{eval-rst}
+.. autoclass:: regstack.backends.protocols.UserRepoProtocol
+   :members:
+
+.. autoclass:: regstack.backends.protocols.PendingRepoProtocol
+   :members:
+
+.. autoclass:: regstack.backends.protocols.BlacklistRepoProtocol
+   :members:
+
+.. autoclass:: regstack.backends.protocols.LoginAttemptRepoProtocol
+   :members:
+
+.. autoclass:: regstack.backends.protocols.MfaCodeRepoProtocol
+   :members:
+
+.. autoclass:: regstack.backends.protocols.MfaVerifyOutcome
+   :members:
+
+.. autoclass:: regstack.backends.protocols.MfaVerifyResult
+   :members:
+
+.. autoexception:: regstack.backends.protocols.UserAlreadyExistsError
+
+.. autoexception:: regstack.backends.protocols.PendingAlreadyExistsError
+```
+
+## Models
+
+The persisted data shapes. `BaseUser` is the canonical user document;
+`UserCreate` validates registration input; `UserPublic` is what the
+API returns (omits the password hash). The other models drive
+verification, lockout, and SMS MFA.
+
+```{eval-rst}
+.. autoclass:: regstack.models.user.BaseUser
+   :members:
+   :exclude-members: model_config, model_fields, model_computed_fields
+
+.. autoclass:: regstack.models.user.UserCreate
+   :members:
+   :exclude-members: model_config, model_fields, model_computed_fields
+
+.. autoclass:: regstack.models.user.UserPublic
+   :members:
+   :exclude-members: model_config, model_fields, model_computed_fields
+
+.. autoclass:: regstack.models.pending_registration.PendingRegistration
+   :members:
+   :exclude-members: model_config, model_fields, model_computed_fields
+
+.. autoclass:: regstack.models.login_attempt.LoginAttempt
+   :members:
+   :exclude-members: model_config, model_fields, model_computed_fields
+
+.. autoclass:: regstack.models.mfa_code.MfaCode
+   :members:
+   :exclude-members: model_config, model_fields, model_computed_fields
+```
+
+## Email + SMS
+
+Pluggable transports for the verification / reset / change-email
+emails and the SMS MFA codes. Implement `EmailService` or `SmsService`
+to plug in a provider that isn't bundled (Postmark, SendGrid,
+MessageBird, …) and pass the instance to `regstack.set_email_backend`
+/ `set_sms_backend`.
+
+### Email
+
+```{eval-rst}
+.. autoclass:: regstack.email.base.EmailMessage
+   :members:
+
+.. autoclass:: regstack.email.base.EmailService
+   :members:
+
+.. autoclass:: regstack.email.console.ConsoleEmailService
+   :members:
+
+.. autoclass:: regstack.email.composer.MailComposer
+   :members:
+
+.. autofunction:: regstack.email.factory.build_email_service
+```
+
+### SMS
+
+```{eval-rst}
+.. autoclass:: regstack.sms.base.SmsMessage
+   :members:
+
+.. autoclass:: regstack.sms.base.SmsService
+   :members:
+
+.. autofunction:: regstack.sms.base.is_valid_e164
+
+.. autoclass:: regstack.sms.null.NullSmsService
+   :members:
+
+.. autofunction:: regstack.sms.factory.build_sms_service
+```
+
+## Hooks
+
+The event bus regstack uses to fire side-effect notifications
+(`user_registered`, `password_changed`, etc.) without coupling auth
+code to host concerns like CRMs or analytics. See the
+[Embedding guide](embedding.md#subscribing-to-events) for examples.
+
+```{eval-rst}
+.. autoclass:: regstack.hooks.events.HookRegistry
+   :members:
+
+.. autodata:: regstack.hooks.events.KNOWN_EVENTS
+```
+
+## Routers
+
+Hosts normally access these via the `regstack.router` and
+`regstack.ui_router` properties; the builder functions are public for
+hosts that want to compose differently.
+
+```{eval-rst}
+.. autofunction:: regstack.routers.build_router
+
+.. autofunction:: regstack.ui.pages.build_ui_router
+
+.. autofunction:: regstack.ui.pages.build_ui_environment
+
+.. autofunction:: regstack.ui.pages.default_static_dir
+```

{regstack-0.2.2 → regstack-0.2.4}/docs/architecture.md

@@ -72,7 +72,6 @@ The façade exposes:
 - `backend` — the active `regstack.backends.base.Backend`.
 - `install_schema()` — install indexes (Mongo) or run
   [Alembic](https://alembic.sqlalchemy.org/) migrations (SQL).
-  `install_indexes()` is kept as a back-compat alias.
 - `aclose()` — tear down the backend's connection pool.
 - `bootstrap_admin(email, password)`,
   `add_template_dir(path)`, `set_email_backend(...)`,

{regstack-0.2.2 → regstack-0.2.4}/docs/changelog.md

@@ -3,6 +3,67 @@
 All notable changes to this project are documented here. Versions follow
 [Semantic Versioning](https://semver.org/) once `1.0.0` ships.
 
+## 0.2.4 — 2026-04-28
+
+**Breaking** — every back-compat shim left over from the
+multi-backend refactor has been removed.
+
+### Removed
+
+- `RegStack.install_indexes()` — the 0.1.x alias for
+  `install_schema()`. Call `install_schema()`.
+- `ObjectIdStr` alias for `IdStr` in `regstack.models._objectid`.
+  Import `IdStr` directly.
+- `__all__`-based re-exports of `UserAlreadyExistsError`,
+  `PendingAlreadyExistsError`, `MfaVerifyOutcome`, and
+  `MfaVerifyResult` from `regstack.backends.mongo.repositories.*` and
+  the package `__init__`. Their canonical home is
+  `regstack.backends.protocols`; that's where every consumer in the
+  package itself already imports them.
+
+### Migration
+
+| Old                                                                              | New                                                            |
+|----------------------------------------------------------------------------------|----------------------------------------------------------------|
+| `await regstack.install_indexes()`                                               | `await regstack.install_schema()`                              |
+| `from regstack.models._objectid import ObjectIdStr`                              | `from regstack.models._objectid import IdStr`                  |
+| `from regstack.backends.mongo.repositories.user_repo import UserAlreadyExistsError`     | `from regstack.backends.protocols import UserAlreadyExistsError`     |
+| `from regstack.backends.mongo.repositories.pending_repo import PendingAlreadyExistsError` | `from regstack.backends.protocols import PendingAlreadyExistsError`  |
+| `from regstack.backends.mongo.repositories.mfa_code_repo import MfaVerifyOutcome, MfaVerifyResult` | `from regstack.backends.protocols import MfaVerifyOutcome, MfaVerifyResult` |
+
+The internal Mongo helper
+`regstack.backends.mongo.indexes.install_indexes(db, config)` is
+unchanged — that's the function `MongoBackend.install_schema` calls
+to actually create the indexes.
+
+## 0.2.3 — 2026-04-28
+
+**Docs-only release.** API reference rewritten around the current
+package layout, public surface gained proper Google-style docstrings.
+
+### Changed
+
+- ``docs/api.md`` restructured around the post-multi-backend package
+  layout (``regstack.backends.{base,protocols,factory,mongo,sql}`` and
+  friends). Each section now opens with a one-paragraph orientation
+  before the autodoc directives. The pre-refactor
+  ``regstack.db.repositories.*`` references that rendered empty are
+  gone.
+- Added Google-style docstrings (purpose summary + Args / Returns /
+  Raises) to the most-touched public methods on ``RegStack``,
+  ``JwtCodec``, ``PasswordHasher``, ``LockoutService``,
+  ``AuthDependencies``, ``HookRegistry``, ``EmailService``,
+  ``SmsService``, ``build_router``, ``build_ui_router``,
+  ``build_ui_environment``, ``default_static_dir``, ``Clock`` /
+  ``SystemClock`` / ``FrozenClock``.
+- Dataclass field documentation moved to PEP 258 attribute docstrings
+  on ``TokenPayload``, ``LockoutDecision``, ``EmailMessage``,
+  ``SmsMessage``, ``MfaVerifyResult`` — autodoc now renders each field
+  with its description without the "duplicate object description"
+  warnings the napoleon ``Attributes:`` block was triggering.
+- ``MfaVerifyOutcome`` enum docstring reformatted as a bullet list
+  (the napoleon ``Members:`` block isn't a recognised section).
+
 ## 0.2.2 — 2026-04-28
 
 **Docs-only release.**

{regstack-0.2.2 → regstack-0.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "regstack"
-version = "0.2.2"
+version = "0.2.4"
 description = "Embeddable user registration, login, and account management for FastAPI apps. SQLite / Postgres / MongoDB."
 readme = "README.md"
 requires-python = ">=3.11"