Metadata-Version: 2.4
Name: spring-dancer-sikits
Version: 0.1.2
Summary: A modular Python toolkit
Project-URL: Homepage, https://github.com/luvMagi/Spring-Dancer-SI-Kits
Project-URL: Repository, https://github.com/luvMagi/Spring-Dancer-SI-Kits
Project-URL: Issues, https://github.com/luvMagi/Spring-Dancer-SI-Kits/issues
Project-URL: Documentation, https://github.com/luvMagi/Spring-Dancer-SI-Kits#readme
Author-email: luvmagi <luvmagi@outlook.com>
License: MIT
License-File: LICENSE
Keywords: toolkit
Requires-Python: >=3.13
Requires-Dist: coverage>=7.14.0
Requires-Dist: numpy>=2.4.5
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: pandas>=3.0.3
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pytest-cov>=7.1.0
Requires-Dist: pytest>=9.0.3
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: sqlglot>=23.0.0
Requires-Dist: xlwings>=0.35.3
Description-Content-Type: text/markdown

# Spring-Dancer-SI-Kits

A modular Python utility library for internal tooling.
Covers string manipulation, WBS project management, JSON diffing, typed settings, serialization, and more.

- **Python >= 3.13**
- **License:** MIT
- **Author:** luvmagi

---

## Project Structure

```
Spring-Dancer-SI-Kits/
│
├── src/sikits/                        # Library source
│   ├── textcraft/                     # Text & string utilities
│   │   ├── string_nameing.py          # CaseUtils — naming convention converter & branch-name generator
│   │   └── class_str.py               # class_str() — recursive pretty-printer for plain classes
│   │
│   ├── serialization/                 # Serialization & settings
│   │   ├── base.py                    # JsonMixin — dataclass JSON/YAML serialization mixin
│   │   └── setting.py                 # SettingRegister — generates typed Python class from config file
│   │
│   ├── wbs/                           # Work Breakdown Structure
│   │   ├── core/
│   │   │   ├── base.py                # WBS base models
│   │   │   └── mapping.py             # Field mapping logic
│   │   ├── schema/
│   │   │   ├── backend.py             # Backend WBS schema
│   │   │   └── frontend.py            # Frontend WBS schema
│   │   ├── io/
│   │   │   ├── csv_reader.py          # Read WBS from CSV
│   │   │   ├── csv_writer.py          # Write WBS to CSV
│   │   │   ├── excel_writer.py        # Write WBS to Excel
│   │   │   ├── json_reader.py         # Read WBS from JSON
│   │   │   └── json_writer.py         # Write WBS to JSON
│   │   ├── dashboard/
│   │   │   ├── calc/
│   │   │   │   ├── assignee.py        # Per-assignee metrics
│   │   │   │   ├── burndown.py        # Burndown chart data
│   │   │   │   ├── funnel.py          # Status funnel
│   │   │   │   └── review_lag.py      # Review lag analysis
│   │   │   └── writer.py              # Dashboard output writer
│   │   └── snapshot/
│   │       └── snapshot.py            # WBS snapshot
│   │
│   ├── json_diff/                     # JSON diff engine
│   │   ├── core/
│   │   │   ├── differ.py              # Core diff logic
│   │   │   ├── key_detector.py        # Key detection strategies
│   │   │   └── strategies.py          # Diff strategies
│   │   ├── schema/
│   │   │   ├── config.py              # Diff configuration schema
│   │   │   └── result.py              # Diff result schema
│   │   ├── io/
│   │   │   ├── json_writer.py         # Write diff as JSON
│   │   │   └── markdown_writer.py     # Write diff as Markdown
│   │   └── exceptions.py              # Diff exceptions
│   │
│   ├── decotextual/                   # Decorator utilities
│   │   ├── decorators.py              # Decorator definitions
│   │   ├── deco_app.py                # Decorator application helpers
│   │   ├── _linear.py                 # Linear execution helper
│   │   └── _stop.py                   # Stop condition helper
│   │
│   ├── database/                      # Database access helpers
│   │   ├── handler.py                 # TableHandler
│   │   └── model/                     # DB schema models
│   │       └── schema.py              # Table, Column, Index
│   ├── dataframe/                     # DataFrame utilities
│   ├── excel/                         # Excel read/write helpers
│   └── image/
│       └── image_to_ico.py            # Image → ICO converter
│
├── tests/                             # Test suite
│   ├── sikits/
│   │   ├── textcraft/
│   │   │   └── test_string_nameing.py
│   │   └── serialization/
│   │       └── test_setting.py
│   └── resource/                      # Test input/output fixtures
│       └── serialization/setting/
│           ├── input.toml / .yaml / .yml / .json / empty.json
│           └── output_*.py            # Generated files (inspectable)
│
├── docs/Project-SpringDancer-Sikits/  # Module documentation
│   ├── serialization/
│   │   ├── base.md
│   │   └── setting.md
│   └── textcraft/
│       └── string_nameing.md (utils-string_nameing.md)
│
├── pyproject.toml                     # Project metadata & pytest config
├── CLAUDE.md                          # AI assistant context
└── README.md
```

---

## Modules

### `sikits.textcraft`

| File | Class / Function | Description |
|---|---|---|
| `string_nameing.py` | `CaseUtils` | Convert strings between 11 naming conventions (snake_case, camelCase, PascalCase, kebab-case …). Handles full-width (全角) characters and Japanese punctuation. |
| `string_nameing.py` | `CaseUtils.to_branch_name` | Convert a GitHub issue title to a valid git branch name. Strips illegal chars, normalizes separators, supports Japanese input. |
| `class_str.py` | `class_str` | Recursive pretty-printer for plain Python objects — used by generated settings classes. |

### `sikits.serialization`

| File | Class | Description |
|---|---|---|
| `base.py` | `JsonMixin` | `@dataclass` mixin that adds `load_dict`, `load_file`, `save_file`, `to_json_string`. Supports nested `JsonMixin`, `Enum`, `Optional[T]`, `list[JsonMixin]`. |
| `setting.py` | `SettingRegister` | Reads a TOML / YAML / JSON config file and generates a fully-typed Python class. The generated class loads from the config file at runtime — no values are baked in. |

**Settings workflow:**

```python
from pathlib import Path
from sikits.serialization.setting import SettingRegister

# Generate once (during development / CI)
SettingRegister(Path("config/settings.toml")).to_class_file(Path("src/myapp/settings.py"))
```

```python
# Use everywhere — dynamically loaded at startup
from myapp.settings import Setting

print(Setting.db.host)
print(Setting.servers[0].name)
```

### `sikits.wbs`

Work Breakdown Structure toolkit. Reads/writes project task data (CSV, JSON, Excel) and computes dashboard metrics (burndown, assignee load, review lag, status funnel).

### `sikits.json_diff`

JSON diff engine with pluggable key-detection and output strategies. Produces structured diff results exportable as JSON or Markdown.

### `sikits.decotextual`

Decorator utilities for contextual text processing pipelines.

### `sikits.database`

Database modeling toolkit for PostgreSQL and Oracle.

| File | Class / Function | Description |
|---|---|---|
| `model/schema.py` | `Table`, `Column`, `Index` | Unified Pydantic Dataclass models for database objects. Compatible with `JsonMixin`. |
| `handler.py` | `TableHandler` | Converts between DDL (Postgres/Oracle) and internal models. Supports multi-statement DDL and index extraction. |

---

## Installation

```bash
# Install from PyPI
pip install spring-dancer-sikits

# Editable install (development)
pip install -e .

# Or with uv
uv sync
```

## Quickstart

```python
from sikits import CaseUtils, JsonDiffer, SettingRegister, TableHandler
```

## Release

```bash
python -m build
twine upload dist/*
```

## Running Tests

```bash
pytest
```

---

## Documentation

Full module docs: [`docs/Project-SpringDancer-Sikits/`](docs/Project-SpringDancer-Sikits/)
