Metadata-Version: 2.4
Name: cuz-toolkit
Version: 0.3.0
Summary: A collection of Django utilities: Admin mixins, testing helpers, and common patterns
Project-URL: Homepage, https://github.com/froggen/django-toolkit
Project-URL: Repository, https://github.com/froggen/django-toolkit
Author-email: Ivan <iven12345678900@gmail.com>
License: MIT
Keywords: admin,django,mixin,permission,testing,toolkit
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.0
Classifier: Framework :: Django :: 4.1
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.13
Requires-Dist: django>=4.0
Provides-Extra: images
Requires-Dist: pillow>=10.0.0; extra == 'images'
Provides-Extra: unfold
Requires-Dist: django-unfold>=0.85.0; extra == 'unfold'
Description-Content-Type: text/markdown

# cuz-toolkit

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

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

## 安裝

```bash
# 一般安裝（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 權限（使用者只能管自己的資料）

```python
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 索引

```python
from toolkit.testing import has_index_on_columns

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

### Unfold Trix 圖片上傳

```python
# 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}}
```

## 開發

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

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

## License

MIT
