moss-mop 0.1.0__tar.gz

moss_mop-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: moss-mop
+Version: 0.1.0
+Summary: Lightweight FastAPI + SQLAlchemy backend toolkit with logging, CRUD, and utilities
+Requires-Python: >=3.12
+Requires-Dist: ascii-colors>=0.11.6
+Requires-Dist: fastapi>=0.124.4
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: sqlalchemy>=2.0.45
+Requires-Dist: structlog>=25.5.0

moss_mop-0.1.0/README.md

@@ -0,0 +1,249 @@
+# MoP
+
+MoP is a lightweight Python backend framework built on FastAPI and SQLAlchemy, providing core functionality modules for building modern web applications.
+
+## Features
+
+- **Configuration Management**: Flexible configuration system with easy-to-use settings
+- **Database Support**: Both synchronous and asynchronous database sessions with SQLAlchemy
+- **Entity Framework**: Base entity class for consistent data modeling
+- **Error Handling**: Centralized error handling with business error codes
+- **Logging**: Structured logging with structlog
+- **Response Formatting**: Consistent API response formatting
+- **CRUD Operations**: Generic CRUD operations with pagination support
+- **Utilities**: Various utility functions for dates, strings, files, and more
+- **Snowflake ID Generation**: Distributed unique ID generation
+
+## Installation
+
+```bash
+pip install moss-mop
+```
+
+Or using uv:
+
+```bash
+uv add moss-mop
+```
+
+## Requirements
+
+- Python 3.12+
+- FastAPI 0.124.4+
+- SQLAlchemy 2.0.45+
+- Pydantic 2.12.5+
+- structlog 25.5.0+
+- ascii-colors 0.11.6+
+
+## Project Structure
+
+```
+mop/
+├── conf/                # Configuration management
+├── db/                  # Database connections
+├── entity/              # Base entity class
+├── error/               # Error handling
+├── logging/             # Logging configuration
+├── response/            # Response formatting
+├── crud/                # CRUD operations
+├── util/                # Utility functions
+└── snowflake.py         # Snowflake ID generation
+```
+
+## Quick Start
+
+### 1. Configuration
+
+```python
+from mop.conf import settings
+
+# Access configuration settings
+print(settings.APP_NAME)
+print(settings.DATABASE_URL)
+```
+
+### 2. Database Setup
+
+```python
+from mop.db import session, async_session
+from sqlalchemy import select
+from your_model import User
+
+# Synchronous session
+with session() as db:
+    users = db.execute(select(User)).scalars().all()
+    print(users)
+
+# Asynchronous session
+async with async_session() as db:
+    users = await db.execute(select(User))
+    users = users.scalars().all()
+    print(users)
+```
+
+### 3. Creating Models
+
+```python
+from mop.entity import Entity
+from sqlalchemy import Column, String
+
+
+class User(Entity):
+    __tablename__ = "users"
+
+    username = Column(String(50), unique=True, index=True)
+    email = Column(String(100), unique=True, index=True)
+```
+
+### 4. Error Handling
+
+```python
+from mop.error import BusinessError, ErrCode
+
+# Raise business error
+raise BusinessError(ErrCode.USER_NOT_FOUND, "User not found")
+```
+
+### 5. Logging
+
+```python
+from mop.logging import logger
+
+# Log messages
+logger.info("User logged in", user_id=123)
+logger.error("Failed to process request", error="Invalid input")
+```
+
+### 6. Response Formatting
+
+```python
+from mop.response import Response, PageResponse
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.get("/users")
+async def get_users():
+    users = [{"id": 1, "name": "John"}, {"id": 2, "name": "Jane"}]
+    return Response(data=users, message="Success")
+
+
+@app.get("/users/page")
+async def get_users_page():
+    users = [{"id": 1, "name": "John"}, {"id": 2, "name": "Jane"}]
+    return PageResponse(data=users, total=100, page=1, page_size=20)
+```
+
+### 7. CRUD Operations
+
+```python
+from mop.crud import CRUDBase
+from your_model import User, UserCreate, UserUpdate
+
+# Create CRUD instance
+user_crud = CRUDBase(User)
+
+# Create user
+user = user_crud.create(db, obj_in=UserCreate(username="test", email="test@example.com"))
+
+# Get user by ID
+user = user_crud.get(db, id=1)
+
+# Update user
+user = user_crud.update(db, db_obj=user, obj_in=UserUpdate(email="new@example.com"))
+
+# Delete user
+user_crud.remove(db, id=1)
+
+# Get users with pagination
+users, total = user_crud.get_multi(db, page=1, page_size=10)
+```
+
+### 8. Snowflake ID Generation
+
+```python
+from mop.snowflake import SnowflakeGenerator
+
+# Create generator instance
+generator = SnowflakeGenerator(datacenter_id=1, worker_id=1)
+
+# Generate unique ID
+unique_id = generator.generate()
+print(unique_id)
+```
+
+## Utilities
+
+### Date Utilities
+
+```python
+from mop.util.dates import format_datetime, parse_datetime
+
+# Format datetime
+formatted = format_datetime(datetime.now())
+print(formatted)
+
+# Parse datetime
+parsed = parse_datetime("2023-01-01 12:00:00")
+print(parsed)
+```
+
+### String Utilities
+
+```python
+from mop.util.strings import random_string, is_email_valid
+
+# Generate random string
+rand_str = random_string(10)
+print(rand_str)
+
+# Check if email is valid
+is_valid = is_email_valid("test@example.com")
+print(is_valid)
+```
+
+### File Utilities
+
+```python
+from mop.util.files import read_file, write_file
+
+# Read file
+content = read_file("test.txt")
+print(content)
+
+# Write file
+write_file("test.txt", "Hello, World!")
+```
+
+## Changelog
+
+### Version 0.1.0 (2025-12-15)
+
+#### Added
+- Initial release of MoP framework
+- Configuration management module
+- Database support with synchronous and asynchronous sessions
+- Base entity class for data modeling
+- Centralized error handling system
+- Structured logging configuration
+- Consistent API response formatting
+- Generic CRUD operations with pagination
+- Utility functions for dates, strings, files, and more
+- Snowflake ID generation for distributed systems
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License
+
+## Author
+
+- **puras** - [puras.he@gmail.com](mailto:puras.he@gmail.com)
+
+## GitHub
+
+[https://github.com/puras/mop](https://github.com/puras/mop)

moss_mop-0.1.0/mop/__init__.py

@@ -0,0 +1,3 @@
+__version__ = "0.1.0"
+__author__ = "puras"
+__email__ = "puras.he@gmail.com"

moss_mop-0.1.0/mop/conf/__init__.py

@@ -0,0 +1 @@
+from .settings import *

moss_mop-0.1.0/mop/conf/settings.py

@@ -0,0 +1,133 @@
+import os
+from enum import Enum
+from typing import List
+
+from pydantic.v1 import BaseSettings
+
+
+class Environment(str, Enum):
+    DEVELOPMENT = "dev"
+    PRODUCTION = "prod"
+    TEST = "test"
+
+def get_environment() -> Environment:
+    match os.getenv("APP_ENV", "development").lower():
+        case "prod" | "production":
+            return Environment.PRODUCTION
+        case "test":
+            return Environment.TEST
+        case _:
+            return Environment.DEVELOPMENT
+
+class Settings(BaseSettings):
+    # 基础配置
+    PROJECT_NAME: str = "MOSS"
+    PROJECT_DESCRIPTION: str = ""
+    VERSION: str = "0.1.0"
+    DEBUG: bool = True
+    ENVIRONMENT = get_environment()
+
+    # API配置
+    API_V1_STR: str = "/api/v1"
+    HOST: str = os.getenv("HOST", "0.0.0.0")
+    PORT: int = os.getenv("PORT", 8000)
+    WORKERS: int = 4
+
+    # 日志配置
+    LOG_DIR: str =os.getenv(
+        "LOG_DIR",
+        "logs"
+    )
+    LOG_LEVEL: str = os.getenv(
+        "LOG_LEVEL",
+        "INFO"
+    )
+    LOG_FORMAT: str = os.getenv(
+        "LOG_FORMAT",
+        "json"
+    ) # json or console
+
+    # 安全配置
+    ALLOWED_ORIGINS: List[str] = [
+        "*",
+    ]
+
+    # 数据库配置
+    SNOWFLAKE_DATACENTER_ID: int = os.getenv("SNOWFLAKE_DATACENTER_ID", 0)
+
+    DATABASE_URI: str = os.getenv(
+        "DATABASE_URI",
+        "sqlite:///./instance/moss.db"  # 使用异步SQLite驱动
+    )
+
+    ASYNC_DATABASE_URI: str = os.getenv(
+        "ASYNC_DATABASE_URI",
+        "sqlite+aiosqlite:///./instance/moss.db"  # 使用异步SQLite驱动
+    )
+    DB_TABLE_PREFIX = os.getenv(
+        "DB_TABLE_PREFIX",
+        "mo_"
+    )
+
+    MINIO_ENDPOINT: str = os.getenv(
+        "MINIO_ENDPOINT",
+        "http://127.0.0.1:9000"
+    )
+
+    MINIO_SHARE_ENDPOINT: str = os.getenv(
+        "MINIO_SHARE_ENDPOINT",
+        "http://127.0.0.1:9000/minio"
+    )
+
+    MINIO_ACCESS_KEY: str = os.getenv(
+        "MINIO_ACCESS_KEY",
+        ""
+    )
+
+    MINIO_SECRET_KEY: str = os.getenv(
+        "MINIO_SECRET_KEY",
+        ""
+    )
+
+    MINIO_DEFAULT_BUCKET: str = os.getenv(
+        "MINIO_DEFAULT_BUCKET",
+        "mo"
+    )
+
+    STORAGE_TYPE: str = os.getenv(
+        "STORAGE_TYPE",
+        "local"
+    )
+
+    OPENDAL_SCHEME: str = os.getenv(
+        "OPENDAL_SCHEME",
+        "fs"
+    )
+    OPENDAL_FS_ROOT: str = os.getenv(
+        "OPENDAL_FS_ROOT",
+        "storage"
+    )
+
+    TEMP_DIR: str = os.getenv(
+        "TEMP_DIR",
+        "temp"
+    )
+
+    AUTH_SECRET_KEY: str = os.getenv(
+        "AUTH_SECRET_KEY",
+        "09d25e094faa6ca2556c818166b7a9563b93f7099f6f0f4caa6cf63b88e8d3e7"
+    )
+    AUTH_SECRET_ALGORITHM: str = os.getenv(
+        "AUTH_SECRET_ALGORITHM",
+        "HS256"
+    )
+    AUTH_ACCESS_TOKEN_EXPIRE: int = os.getenv(
+        "AUTH_ACCESS_TOKEN_EXPIRE",
+        30
+    )
+
+    class Config:
+        env_file = ".env"
+        case_sensitive = True
+
+settings = Settings()

moss_mop-0.1.0/mop/crud/__init__.py

@@ -0,0 +1,2 @@
+from .page import *
+from .crud import *

moss_mop-0.1.0/mop/crud/crud.py

@@ -0,0 +1,164 @@
+from typing import Generic, TypeVar
+
+from sqlalchemy import select, func
+
+from .page import ListSlice
+from mop.db import AsyncSessionLocal, SessionLocal
+from mop.entity import BaseEntity
+from mop.error import DATA_NOT_FOUND, BizError
+
+T = TypeVar("T", bound=BaseEntity)
+
+
+class CrudBiz(Generic[T]):
+    def __init__(self, model: type[T]):
+        self.model = model
+
+    def sync_find_all(self, **kwargs):
+        filters = [self.model.deleted == False]
+
+        for key, value in kwargs.items():
+            if hasattr(self.model, key):
+                filters.append(getattr(self.model, key) == value)
+
+        with SessionLocal() as db:
+            try:
+                ret = db.execute(select(self.model).where(*filters))
+                items = ret.scalars().all()
+                return items
+            finally:
+                db.close()
+
+    def sync_find_by_id(self, item_id: str):
+        filters = [self.model.id == item_id, self.model.deleted == False]
+        with SessionLocal() as db:
+            try:
+                ret = db.execute(select(self.model).where(*filters))
+                ret = ret.scalars().first()
+                if not ret:
+                    raise BizError.init(DATA_NOT_FOUND)
+                return ret
+            finally:
+                db.close()
+
+    async def find_all(self, **kwargs):
+        filters = [self.model.deleted == False]
+
+        for key, value in kwargs.items():
+            if hasattr(self.model, key):
+                filters.append(getattr(self.model, key) == value)
+
+        async with AsyncSessionLocal() as db:
+            try:
+                ret = await db.execute(select(self.model).where(*filters))
+                items = ret.scalars().all()
+                return items
+            finally:
+                await db.close()
+
+    async def count_by(self, **kwargs):
+        filters = [self.model.deleted == False]
+        for key, value in kwargs.items():
+            if hasattr(self.model, key):
+                filters.append(getattr(self.model, key) == value)
+        primary_column = self.model.__mapper__.primary_key[0]
+        async with AsyncSessionLocal() as db:
+            try:
+                cnt = await db.execute(select(func.count(primary_column)).where(*filters))
+                return cnt.scalar()
+            finally:
+                await db.close()
+
+    async def _count_by(self, db: AsyncSessionLocal, *filters):
+        primary_column = self.model.__mapper__.primary_key[0]
+        cnt = await db.execute(select(func.count(primary_column)).where(*filters))
+        return cnt.scalar()
+
+    async def find_by(self, page_num: int = 1, page_size: int = 100, **kwargs):
+        filters = [self.model.deleted == False]
+
+        for key, value in kwargs.items():
+            if hasattr(self.model, key):
+                filters.append(getattr(self.model, key) == value)
+
+        skip = (page_num - 1) * page_size
+        async with AsyncSessionLocal() as db:
+            try:
+                print(filters)
+                total = await self._count_by(db, *filters)
+                ret = await db.execute(
+                    select(self.model).where(*filters).offset(skip).limit(page_size)
+                )
+                items = ret.scalars().all()
+                return ListSlice(
+                    items=items, total=total, page_num=page_num, page_size=page_size
+                )
+            finally:
+                await db.close()
+
+    async def find_by_id(self, item_id: str):
+        filters = [self.model.id == item_id, self.model.deleted == False]
+        async with AsyncSessionLocal() as db:
+            try:
+                ret = await db.execute(select(self.model).where(*filters))
+                ret = ret.scalars().first()
+                if not ret:
+                    raise BizError.init(DATA_NOT_FOUND)
+                return ret
+            finally:
+                await db.close()
+
+    async def find_one(self, **kwargs):
+        filters = [self.model.deleted == False]
+
+        for key, value in kwargs.items():
+            if hasattr(self.model, key):
+                filters.append(getattr(self.model, key) == value)
+
+        async with AsyncSessionLocal() as db:
+            try:
+                ret = await db.execute(select(self.model).where(*filters))
+                item = ret.scalars().first()
+                return item
+            finally:
+                await db.close()
+
+    async def create(self, **kwargs):
+        item = self.model(**kwargs)
+        item.default_created()
+        async with AsyncSessionLocal() as db:
+            try:
+                db.add(item)
+                await db.commit()
+                await db.refresh(item)
+                return item
+            finally:
+                await db.close()
+
+    async def update(self, item_id: str, **kwargs):
+        item = await self.find_by_id(item_id)
+
+        other = self.model(**kwargs)
+        item.update_attrs(other)
+
+        async with AsyncSessionLocal() as db:
+            try:
+                db.add(item)
+                await db.commit()
+                await db.refresh(item)
+                return item
+            finally:
+                await db.close()
+
+    async def delete(self, item_id: str) -> bool:
+        item = await self.find_by_id(item_id)
+        item.default_deleted()
+        async with AsyncSessionLocal() as db:
+            try:
+                db.add(item)
+                await db.commit()
+                await db.refresh(item)
+                return True
+            finally:
+                await db.close()
+        return False

moss_mop-0.1.0/mop/crud/page.py

@@ -0,0 +1,11 @@
+from typing import List, TypeVar, Generic
+
+from pydantic import BaseModel, Field
+
+T  = TypeVar("T")
+
+class ListSlice(BaseModel, Generic[T]):
+    items: List[T] = Field(description="当前页的数据集合")
+    total: int = Field(description="总记录数")
+    page_num: int = Field(1, description="当前页面， 默认为1")
+    page_size: int = Field(10, description="每页的数据量，默认为10")

moss_mop-0.1.0/mop/db/__init__.py

@@ -0,0 +1,3 @@
+from .base import *
+from .session import *
+from .async_session import *

moss_mop-0.1.0/mop/db/async_session.py

@@ -0,0 +1,33 @@
+from typing import AsyncGenerator, Annotated
+
+from fastapi import Depends
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+from sqlalchemy.orm import sessionmaker
+
+from mop.conf import settings
+
+async_engine = create_async_engine(
+    settings.ASYNC_DATABASE_URI,
+    echo=settings.DEBUG
+)
+
+AsyncSessionLocal = sessionmaker(
+    async_engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+    autocommit=False,
+    autoflush=False,
+)
+
+async def get_async_session() -> AsyncGenerator[AsyncSession, None]:
+    """
+    获取数据库会话依赖
+    :return:
+    """
+    async with AsyncSessionLocal() as session:
+        try:
+            yield session
+        finally:
+            await session.close()
+
+AsyncSessionDep = Annotated[AsyncSession, Depends(get_async_session)]

moss_mop-0.1.0/mop/db/base.py

@@ -0,0 +1,12 @@
+from sqlalchemy.orm import declared_attr, declarative_base
+
+from mop.conf import settings
+from mop.util.strings import to_underline
+
+
+class Base:
+    @declared_attr
+    def __tablename__(self):
+        return f"{settings.DB_TABLE_PREFIX}{to_underline(self.__name__)}"
+
+Base = declarative_base(cls=Base)

moss_mop-0.1.0/mop/db/session.py

@@ -0,0 +1,29 @@
+from typing import Annotated
+
+from fastapi import Depends
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker, Session
+
+from mop.conf import settings
+
+engine = create_engine(
+    settings.DATABASE_URI,
+    echo=settings.DEBUG
+)
+
+SessionLocal = sessionmaker(
+    engine,
+    class_=Session,
+    expire_on_commit=False,
+    autocommit=False,
+    autoflush=False,
+)
+
+def get_session():
+    with SessionLocal() as session:
+        try:
+            yield session
+        finally:
+            session.close()
+
+SessionDep = Annotated[Session, Depends(get_session)]

moss_mop-0.1.0/mop/entity/__init__.py

@@ -0,0 +1 @@
+from .entity import *

moss_mop-0.1.0/mop/entity/entity.py

@@ -0,0 +1,36 @@
+from datetime import datetime
+
+from sqlalchemy import Column, String, Boolean, DateTime, text, Integer
+
+from mop.db import Base
+from mop.snowflake import IDWorker
+
+
+class BaseEntity(Base):
+    __abstract__ = True
+    id = Column(Integer, primary_key=True, index=True)
+    tenant_id = Column(String(32), nullable=False)
+    deleted = Column(Boolean, nullable=False, server_default=text("false"))
+    created_by = Column(String(32), nullable=True)
+    created_at = Column(DateTime, nullable=True, default=datetime.now)
+    updated_by = Column(String(32), nullable=True)
+    updated_at = Column(DateTime, nullable=True, default=datetime.now)
+    deleted_by = Column(String(32), nullable=True)
+    deleted_at = Column(DateTime, nullable=True)
+
+    def default_created(self):
+        self.id = IDWorker.gen_id()
+        self.tenant_id = '000000'
+
+    def update_attrs(self, other):
+        for attr in other.__dict__.keys():
+            if hasattr(self, attr) and attr != 'id' and attr != '_sa_instance_state':
+                setattr(self, attr, getattr(other, attr))
+        self.updated_at = datetime.now()
+
+    def default_deleted(self):
+        self.deleted = True
+        self.deleted_at = datetime.now()
+
+
+

moss_mop-0.1.0/mop/error/__init__.py

@@ -0,0 +1,2 @@
+from .err_code import *
+from .biz_error import *