cuz-toolkit 0.3.0

A collection of Django utilities: Admin mixins, testing helpers, and common patterns

cuz-toolkit

自家 Django 常用功能庫：Admin 權限 Mixin、ECPay 協議層、台灣地址／銀行資料、測試工具、Unfold 擴充。

完整功能索引見 INDEX.md（每個公開 symbol 一行「做什麼＋import 路徑」；改公開 API 時同步更新）。

安裝

# 一般安裝（PyPI）
uv add cuz-toolkit

# 本機開發（editable，改完立即生效）
uv add --editable ../cuz-toolkit

套件 import 名稱是 toolkit：from toolkit.admin import OwnerMixin。

模組總覽

模組	做什麼
toolkit.admin	Django Admin 權限控制 Mixin（Owner／ReadOnly／CRUD／ActionsOnly…，含 Inline 版）
toolkit.ecpay	ECPay 綠界協議層：CheckMacValue 簽名、回呼驗證、付款方式常數（不含業務邏輯）
toolkit.testing	測試用 DB 檢查：資料表約束／索引存在性驗證（跨資料庫）
toolkit.tw_address	台灣縣市／區域連動下拉選單的 Admin 整合
toolkit.tw_banks	台灣銀行代碼查詢＋Django choices
toolkit.unfold	Unfold 擴充：Trix 編輯器圖片上傳、UI 中文翻譯
toolkit.utils	通用工具：唯一檔名 upload_to 產生器
toolkit.pytest_plugin	pytest plugin（自動啟用）：coverage 舊檔清理、VSCode xdist worker 修正

快速上手

Admin 權限（使用者只能管自己的資料）

from django.contrib import admin
from toolkit.admin import OwnerMixin
from unfold.admin import ModelAdmin

@admin.register(Project)
class ProjectAdmin(OwnerMixin, ModelAdmin):
    owner_field = "user"          # 支援巢狀路徑：如 "order__user"

測試驗 DB 索引

from toolkit.testing import has_index_on_columns

def test_status_index_exists():
    assert has_index_on_columns("invoice", ["status", "created_at"])

Unfold Trix 圖片上傳

# settings.py：INSTALLED_APPS 加 "toolkit.unfold"（須排在 "unfold.contrib.forms" 之前）
# urls.py：path("", include("toolkit.unfold.urls"))
from django.db import models
from toolkit.unfold import TrixUploadWidget

class ArticleAdmin(ModelAdmin):
    formfield_overrides = {models.TextField: {"widget": TrixUploadWidget}}

開發

uv run pytest
uv run mypy src/
uv run ruff check src/

改到公開 API（新增／改名／刪除 symbol、改設定需求）→ 同步更新 INDEX.md。

License

MIT