Metadata-Version: 2.4
Name: ms-common
Version: 1.4.14
Summary: Shared utilities for Mei Sheng Textiles applications
Author-email: Mei Sheng Textiles Development Team <dev@meisheng.group>
License: Proprietary
Project-URL: Homepage, https://gitea.dev.meisheng.group/Mei_Sheng_Textiles/ms_common_python
Project-URL: Bug Reports, https://gitea.dev.meisheng.group/Mei_Sheng_Textiles/ms_common_python/issues
Project-URL: Source, https://gitea.dev.meisheng.group/Mei_Sheng_Textiles/ms_common_python
Keywords: fastapi,microservices,textiles,manufacturing
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: FastAPI
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.100.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: faststream>=0.5.30
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: postgres
Requires-Dist: psycopg2-binary>=2.9.0; extra == "postgres"
Requires-Dist: asyncpg>=0.28.0; extra == "postgres"
Provides-Extra: consul
Requires-Dist: python-consul>=1.1.0; extra == "consul"
Provides-Extra: messaging
Requires-Dist: faststream[kafka]>=0.5.30; extra == "messaging"
Provides-Extra: telemetry
Requires-Dist: sentry-sdk[fastapi]>=2.0.0; extra == "telemetry"
Requires-Dist: posthog>=3.0.0; extra == "telemetry"

# MS Common Python Package

Shared utilities and services for Mei Sheng Textiles dye house applications.

## Installation

```bash
# From internal PyPI (preferred)
pip install ms-common --index-url https://pypi.dev.meisheng.group/simple/

# With optional extras
pip install ms-common[messaging]   # Kafka via FastStream
pip install ms-common[consul]      # Consul service discovery
pip install ms-common[postgres]    # PostgreSQL support
```

## Features

- **API Key Management** - PostgreSQL, SQLite, and config-based implementations
- **Service Discovery** - Consul-based with fallbacks
- **Kafka Messaging** - Producer/consumer via FastStream
- **Monitoring** - FastAPI health check endpoints
- **Notifications** - Shared notification utilities
- **Textile Constants** - Unit conversions (yards/meters, kg/lbs)

## Quick Start

### API Key Service

```python
from ms_common import create_api_key_service

# PostgreSQL (DH_Production_Manager)
service = create_api_key_service('postgres',
    session_factory=get_async_session,
    user_model=User, api_key_model=ApiKey)

# SQLite (MS_QC_DB)
service = create_api_key_service('sqlite', db_path='/app/data/api_keys.db')

# Config-based (dye_process_manager)
service = create_api_key_service('config', config_keys={'admin': 'key123'})

key_info = await service.validate_api_key(api_key)
```

### Kafka Messaging

```python
from ms_common.messaging.kafka import create_kafka_producer, create_kafka_consumer

# Producer
producer = create_kafka_producer(config)
await producer.send("quality.events", event)

# Consumer
consumer = create_kafka_consumer(config, topics=["quality.events"])
async with consumer.consuming_context():
    async for msg in consumer.get_messages(timeout=10.0):
        handle(msg)
```

### Health Check Endpoints

```python
from fastapi import FastAPI
from ms_common.monitoring.endpoints import create_monitoring_router

app = FastAPI()
app.include_router(create_monitoring_router("my-service"), prefix="/api/v1/monitoring")
```

## Development

```bash
git clone ssh://git@gitea.dev.meisheng.group:2222/Mei_Sheng_Textiles/ms_common_python.git
cd ms_common_python
uv sync --all-extras
uv run pytest
```

## Versioning

Version is defined **once** in `pyproject.toml`. At runtime, `ms_common.__version__`
reads it via `importlib.metadata` -- there is nothing to keep in sync.

## Publishing to PyPI

Use `upload.py` to build and publish. It talks directly to the pypicloud REST API
(no twine dependency, no shell escaping issues).

```bash
# Build and upload the current version
uv run python upload.py

# Bump version first (updates pyproject.toml, then builds + uploads)
uv run python upload.py --bump patch   # 1.3.8 -> 1.3.9
uv run python upload.py --bump minor   # 1.3.8 -> 1.4.0
uv run python upload.py --bump major   # 1.3.8 -> 2.0.0

# Build without uploading
uv run python upload.py --build-only

# List all published versions
uv run python upload.py --list

# Delete a broken version
uv run python upload.py --delete 1.2.0
```

## License

Internal use only -- Mei Sheng Textiles Ltd.
