refactor(rename): rename import package from messaging to messagekit

## Starting point: PEP 423 violation

The library used `python-eventing` as distribution name but `messaging` as
import package name. This violates PEP 423's recommendation that distribution
and import names should match. The mismatch caused recurring confusion in
documentation and onboarding.

## Changes

### Package rename
- Renamed `src/messaging/` directory to `src/messagekit/` via git mv
- Updated all Python imports across 146+ files in src/, tests/, scripts/
- Fixed @patch() string targets that reference module paths

### Distribution name (pyproject.toml)
- `name = "python-eventing"` -> `name = "messagekit"`
- `packages = [{include = "messaging"}]` -> `include = "messagekit"`
- Updated `known_first_party` for deptry and isort
- Updated all coverage threshold paths

### Configuration files
- setup.cfg: all per-file-ignores paths
- .importlinter: root_package and layer references
- docs/source/conf.py: autoapi_dirs path
- .vulture-whitelist.py: comment paths

### Documentation
- README.md: install commands, import examples, naming explanation,
  comparison table, architecture diagrams
- 12 docs/*.md files: import paths, file references, prose

## Result

Distribution name and import name are now both `messagekit`, achieving
PEP 423 compliance. All linters pass (ruff, mypy, lint-imports). Full
test suite passes (228/228). GitHub URLs unchanged (repo rename separate).

Author: FirstUnicorn

.importlinter

@@ -1,12 +1,12 @@
 [importlinter]
-root_package = messaging
+root_package = messagekit
 
 [importlinter:contract:layers]
 name = Clean Architecture layer independence
 type = layers
 layers =
-    messaging.presentation
-    messaging.infrastructure
-    messaging.application
-    messaging.domain
-    messaging.core
+    messagekit.presentation
+    messagekit.infrastructure
+    messagekit.application
+    messagekit.domain
+    messagekit.core

.vulture-whitelist.py

@@ -11,8 +11,8 @@
 # Triggers skip_broker_in_tests fixture execution via pytest dependency injection
 skip_broker_in_tests  # Used in: async_client fixture (sets TESTING_SKIP_BROKER env var)
 
-# === src/messaging/infrastructure/pubsub/broker_config/_factory_helpers.py:34 ===
-# === src/messaging/infrastructure/pubsub/rabbit_broker_config/_factory_helpers.py:36 ===
+# === src/messagekit/infrastructure/pubsub/broker_config/_factory_helpers.py:34 ===
+# === src/messagekit/infrastructure/pubsub/rabbit_broker_config/_factory_helpers.py:36 ===
 # circuit_breaker_factory(msg, context) - required by FastStream middleware interface
 # REFERENCE: https://faststream.ag2.ai/latest/getting-started/middlewares/middleware/
 # NOTE: ARG001 suppressed inline in source. Vulture still detects as unused (expected).

README.md

@@ -26,16 +26,16 @@ Package-first universal event infrastructure for microservices.
 ## Installation
 
 ```bash
-pip install python-eventing
+pip install messagekit
 # or
-poetry add python-eventing
+poetry add messagekit
 ```
 
-**Import package name:** `messaging` (distribution is `python-eventing`)
+**Import package name:** `messagekit` (distribution is `messagekit`)
 
 ```python
-from messaging.core import BaseEvent
-from messaging.infrastructure import SqlAlchemyOutboxRepository
+from messagekit.core import BaseEvent
+from messagekit.infrastructure import SqlAlchemyOutboxRepository
 ```
 
 **Requirements:**
@@ -47,15 +47,15 @@ Support scale: `❌` none, `✅` basic, `✅✅` strong, `✅✅✅` first-class
 
 ## Comparison with alternatives
 
-`python-eventing` prioritizes **durable messaging** (transactional outbox + CDC) and **Kafka/RabbitMQ integration** over in-process event simplicity:
+`messagekit` prioritizes **durable messaging** (transactional outbox + CDC) and **Kafka/RabbitMQ integration** over in-process event simplicity:
 
-| Capability | `python-eventing` | [`pyventus`](https://github.com/mdapena/pyventus) | [`fastapi-events`](https://github.com/melvinkcx/fastapi-events) | Notes |
+| Capability | `messagekit` | [`pyventus`](https://github.com/mdapena/pyventus) | [`fastapi-events`](https://github.com/melvinkcx/fastapi-events) | Notes |
 | --- | --- | --- | --- | --- |
 | Transactional outbox | ✅✅✅ | ❌ | ❌ | Durable local DB plus outbox boundary is a core feature here |
 | Kafka data plane | ✅✅✅ | ❌ | ❌ | This package is built for Kafka-backed microservice messaging |
 | DLQ handling | ✅✅✅ | ❌ | ❌ | Leverages native RabbitMQ DLX and Kafka Connect DLQ SMT with database bookkeeping |
 | Health checks for eventing runtime | ✅✅✅ | ❌ | ❌ | Outbox health checks plus FastStream ASGI broker health endpoint |
-| Typed cross-service event contracts | ✅✅ | ✅ | ✅✅ | `python-eventing` and `fastapi-events` are stronger on explicit payload modeling |
+| Typed cross-service event contracts | ✅✅ | ✅ | ✅✅ | `messagekit` and `fastapi-events` are stronger on explicit payload modeling |
 | Decorator subscriber registration | ✅✅ | ✅✅✅ | ✅✅ | `EventBus.subscriber(...)` exists now; `pyventus` is still the most polished here |
 | In-process dispatch backend abstraction | ✅✅ | ✅✅✅ | ✅ | `DispatchBackend` exists here; `pyventus` offers a broader processor model |
 | Lifecycle hooks / callbacks | ✅✅ | ✅✅✅ | ✅ | `DispatchHooks` covers dispatch, success, failure, disabled, and debug |
@@ -70,7 +70,7 @@ Support scale: `❌` none, `✅` basic, `✅✅` strong, `✅✅✅` first-class
 
 ## When to use this package
 
-**Use `python-eventing` if you need:**
+**Use `messagekit` if you need:**
 - Guaranteed event delivery via transactional outbox pattern
 - Kafka-based microservice messaging with CDC publishing
 - Dead letter queue handling with database bookkeeping
@@ -220,7 +220,7 @@ flowchart LR
 │                         YOUR SERVICE (FastAPI)                               │
 │                                                                              │
 │  ┌──────────────┐      ┌──────────────────────────────────────────────┐    │
-│  │   Routes     │──┬──▶│      python-eventing (SHARED CONTRACTS)       │    │
+│  │   Routes     │──┬──▶│      messagekit (SHARED CONTRACTS)       │    │
 │  └──────────────┘  │   │                                               │    │
 │                    │   │  • BaseEvent (Pydantic base)                  │    │
 │                    │   │  • IOutboxRepository (Protocol)               │    │
@@ -229,7 +229,7 @@ flowchart LR
 │                    │                       │ Uses contracts                 │
 │                    │                       ▼                                │
 │                    │   ┌──────────────────────────────────────────────┐    │
-│                    │   │         python-eventing (implementations)     │    │
+│                    │   │         messagekit (implementations)     │    │
 │                    │   │                                               │    │
 │                    │   │  ┌────────────────────────────────────────┐  │    │
 │                    │   │  │  WRITE SIDE (Primary)                  │  │    │
@@ -310,7 +310,7 @@ flowchart LR
                  │    │  DOWNSTREAM SERVICES                                 │
                  │    │                                                      │
                  │    │  ┌──────────────────────────────────────────────┐   │
-                 │    │  │  READ SIDE (python-eventing)                 │   │
+                 │    │  │  READ SIDE (messagekit)                 │   │
                  │    │  │                                              │   │
                  │    │  │  @broker.subscriber("user.created")          │   │
                  │    │  │  async def handle(event: UserCreated):       │   │
@@ -412,7 +412,7 @@ async def handle_user_created(event: UserCreatedEvent):  # ✅ Already a Pydanti
 - 🏥 **Native health checks**: `make_ping_asgi` endpoint for broker status
 - 🔀 **Unified API**: Same code works for Kafka, RabbitMQ, NATS, Redis Streams
 
-`python-eventing` uses FastStream for all Kafka/RabbitMQ interactions, giving you a clean, Pythonic API while handling all the low-level complexity.
+`messagekit` uses FastStream for all Kafka/RabbitMQ interactions, giving you a clean, Pythonic API while handling all the low-level complexity.
 
 ## Setup
 
@@ -446,8 +446,8 @@ Initialize the outbox repository and event bus at application startup:
 ```python
 from fastapi import FastAPI
 from sqlalchemy.ext.asyncio import create_async_engine
-from messaging.infrastructure import SqlAlchemyOutboxRepository
-from messaging.core import build_event_bus
+from messagekit.infrastructure import SqlAlchemyOutboxRepository
+from messagekit.core import build_event_bus
 
 app = FastAPI()
 
@@ -473,8 +473,8 @@ The **core pattern** is the transactional outbox - persist events atomically wit
 
 ```python
 from fastapi import Depends
-from messaging.core import BaseEvent
-from messaging.infrastructure import SqlAlchemyOutboxRepository
+from messagekit.core import BaseEvent
+from messagekit.infrastructure import SqlAlchemyOutboxRepository
 
 # Define domain event
 class UserCreated(BaseEvent):
@@ -520,8 +520,8 @@ async def create_user(
 For **decoupled architectures** with multiple side effects per event, use the **EventBus** abstraction layer:
 
 ```python
-from messaging.core import BaseEvent
-from messaging.infrastructure import OutboxEventHandler
+from messagekit.core import BaseEvent
+from messagekit.infrastructure import OutboxEventHandler
 
 # Access EventBus (initialized at startup)
 event_bus = request.app.state.event_bus
@@ -551,16 +551,16 @@ await event_bus.dispatch(UserCreated(...))
 
 ## Distribution
 
-- PyPI distribution name: `python-eventing`
-- Python import package: `messaging`
+- PyPI distribution name: `messagekit`
+- Python import package: `messagekit`
 
 ```python
 # Install
-pip install python-eventing
+pip install messagekit
 
 # Import
-from messaging.core import BaseEvent
-from messaging.infrastructure import SqlAlchemyOutboxRepository
+from messagekit.core import BaseEvent
+from messagekit.infrastructure import SqlAlchemyOutboxRepository
 ```
 
 Services should consume the published package rather than source checkout. Kafka remains shared infrastructure with local producer/consumer clients per service.

coverage.json

@@ -13,9 +13,9 @@
 
 ### Imports Updated
 Changed `from faststream.kafka` → `from faststream.confluent` in:
-- `src/messaging/infrastructure/pubsub/broker_config.py`
-- `src/messaging/infrastructure/pubsub/kafka_publisher.py`
-- `src/messaging/infrastructure/health/outbox_health_check.py`
+- `src/messagekit/infrastructure/pubsub/broker_config.py`
+- `src/messagekit/infrastructure/pubsub/kafka_publisher.py`
+- `src/messagekit/infrastructure/health/outbox_health_check.py`
 - `tests/unit/infrastructure/test_kafka_publisher.py`
 - `tests/unit/infrastructure/test_fake_broker_contract/test_signature_match.py`
 

docs/confluent-backend-migration.md

@@ -22,7 +22,7 @@ Publish events directly to Kafka - no database, no CDC needed.
 **Code example**:
 ```python
 from faststream.kafka import KafkaBroker
-from messaging.infrastructure.pubsub.kafka_publisher import KafkaEventPublisher
+from messagekit.infrastructure.pubsub.kafka_publisher import KafkaEventPublisher
 
 # Create broker and publisher
 broker = KafkaBroker("localhost:9092")
@@ -48,7 +48,7 @@ Write events to database in same transaction as business logic, CDC publishes to
 ```python
 from sqlalchemy.ext.asyncio import AsyncSession
 from python_outbox_core import OutboxPublisherBase
-from messaging.infrastructure.outbox.repository import SqlAlchemyOutboxRepository
+from messagekit.infrastructure.outbox.repository import SqlAlchemyOutboxRepository
 
 # In your transaction
 async with session.begin():

docs/deployment/quickstart-docker-kafka.md

@@ -76,8 +76,8 @@ Kafka Publisher → External broker
 
 ```python
 from fastapi import Depends
-from messaging.core import BaseEvent
-from messaging.infrastructure import SqlAlchemyOutboxRepository
+from messagekit.core import BaseEvent
+from messagekit.infrastructure import SqlAlchemyOutboxRepository
 
 class UserCreated(BaseEvent):
     event_type: str = "user.created"
@@ -107,7 +107,7 @@ async def create_user(
 
 ```python
 from fastapi import Request
-from messaging.infrastructure import OutboxEventHandler
+from messagekit.infrastructure import OutboxEventHandler
 
 @router.post("/users")
 async def create_user(data: CreateUserRequest, request: Request):
@@ -146,7 +146,7 @@ async def create_user(data: CreateUserRequest, request: Request):
 **Solution**: EventBus dispatches to `OutboxEventHandler`, which persists events in the same database transaction as business data.
 
 ```python
-from messaging.infrastructure import OutboxEventHandler
+from messagekit.infrastructure import OutboxEventHandler
 
 # In service layer
 async def create_order(data, session):
@@ -202,7 +202,7 @@ await event_bus.dispatch(OrderPlaced(...))
 **Solution**: Use lifecycle hooks to log/trace all dispatches.
 
 ```python
-from messaging.core import DispatchHooks
+from messagekit.core import DispatchHooks
 
 def log_dispatch(trace):
     logger.info(
@@ -269,7 +269,7 @@ await service.create_user(data)  # EventBus disabled, no DB writes
 **Solution**: Implement custom `DispatchBackend`.
 
 ```python
-from messaging.core import DispatchBackend
+from messagekit.core import DispatchBackend
 import asyncio
 
 class ParallelDispatchBackend(DispatchBackend):

docs/eventbus/usage-guide.md

@@ -49,7 +49,7 @@
 typehints_defaults = "comma"
 
 autoapi_type = "python"
-autoapi_dirs = [str(SRC_DIR / "messaging")]
+autoapi_dirs = [str(SRC_DIR / "messagekit")]
 autoapi_root = "autoapi"
 autoapi_add_toctree_entry = True
 autoapi_keep_files = False  # Don't keep files to avoid stale references

docs/source/conf.py

@@ -1,6 +1,6 @@
 # Consumer transaction management guide
 
-**API Reference:** [IdempotentConsumerBase](https://python-eventing.readthedocs.io/en/latest/autoapi/messaging/infrastructure/messaging/kafka_consumer_base/index.html)
+**API Reference:** [IdempotentConsumerBase](https://python-eventing.readthedocs.io/en/latest/autoapi/messagekit/infrastructure/messaging/kafka_consumer_base/index.html)
 
 **Integration Guide:** [Consume idempotently](https://python-eventing.readthedocs.io/en/latest/integration-guide.html#consume-idempotently)
 
@@ -51,8 +51,8 @@ If either fails, both should roll back together.
 
 ```python
 from faststream.kafka import KafkaBroker
-from messaging.infrastructure.messaging.kafka_consumer_base import IdempotentConsumerBase
-from messaging.infrastructure.persistence.processed_message_store import SqlAlchemyProcessedMessageStore
+from messagekit.infrastructure.messaging.kafka_consumer_base import IdempotentConsumerBase
+from messagekit.infrastructure.persistence.processed_message_store import SqlAlchemyProcessedMessageStore
 
 broker = KafkaBroker()
 

docs/source/consumer-transactions.md

@@ -46,8 +46,8 @@ Service C (Notification Service)
 # service-a/routes.py
 from fastapi import FastAPI, Depends
 from sqlalchemy.ext.asyncio import AsyncSession
-from messaging.infrastructure.outbox import SqlAlchemyOutboxRepository
-from messaging.core import BaseEvent
+from messagekit.infrastructure.outbox import SqlAlchemyOutboxRepository
+from messagekit.core import BaseEvent
 
 app = FastAPI()
 
@@ -118,7 +118,7 @@ CDC detects new row in `outbox_events` and publishes to **Kafka topic: `user.cre
 ```python
 # service-b/consumers.py
 from faststream.kafka import KafkaBroker
-from messaging.infrastructure.pubsub.consumer_base import SqlAlchemyProcessedMessageStore
+from messagekit.infrastructure.pubsub.consumer_base import SqlAlchemyProcessedMessageStore
 
 broker = KafkaBroker("kafka:9092")  # Docker service name
 
@@ -160,8 +160,8 @@ The bridge service (part of standard architecture) runs the Kafka → RabbitMQ f
 ```python
 # eventing-bridge/main.py (thin wrapper service)
 from fastapi import FastAPI
-from messaging.main._initialization.bridge_setup import initialize_production_bridge
-from messaging.config import settings
+from messagekit.main._initialization.bridge_setup import initialize_production_bridge
+from messagekit.config import settings
 
 app = FastAPI(title="Eventing Bridge")
 
@@ -182,7 +182,7 @@ async def startup():
 ```python
 # service-c/consumers.py
 from faststream.rabbit import RabbitBroker
-from messaging.infrastructure.pubsub.consumer_base import SqlAlchemyProcessedMessageStore
+from messagekit.infrastructure.pubsub.consumer_base import SqlAlchemyProcessedMessageStore
 
 rabbit_broker = RabbitBroker("amqp://guest:guest@rabbitmq:5672/")