Import Strategy

grelmicro follows the Django/SQLAlchemy pattern: core API is re-exported from package __init__.py, backends are imported from their submodules.

Principle

Import from	Contains
Package (grelmicro.coordination)	Primitives, protocols, errors, types (what every user needs)
Submodule (grelmicro.coordination.redis)	Backend implementations (infrastructure-specific code)

Rationale

No unnecessary imports. Importing a primitive does not pull in backend client libraries. Users only pay for the backend they choose. A framework helper, such as health_router or metrics_router, lives in grelmicro.integrations, never in a domain package. A test imports each package in a fresh interpreter and checks that no framework, vendor SDK or OpenTelemetry module loads. Two dependencies load at import when they are installed: orjson, which handles the JSON grelmicro reads and writes, and OpenTelemetry in grelmicro.log, which adds the trace context to every record.

Explicit dependencies. A submodule import like from grelmicro.coordination.redis import RedisLockAdapter makes the infrastructure dependency visible at the import site. Grepping for the submodule path finds every file that needs that backend.

Ecosystem convention. Django databases, SQLAlchemy dialects, and Celery brokers all follow this pattern. Backends are selected once in configuration, not scattered across business logic.

Top-level re-exports

Patterns are imported from their domain package (from grelmicro.coordination import Lock), never from the top-level grelmicro package. The domain path is the classification: it names the docs page, the Component, and the backend family. Flat re-exports at the top level were evaluated for 1.0 and rejected, one obvious import per task beats one saved line.