DHI / DHI/python-package-development

Add fluent interface pattern as teaching example

オープン
#36 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る
主要言語
Jupyter Notebook
スター
8
フォーク
1
平均マージ
4分
マージ済み PR(30日)
1

説明

Add a section or exercise covering API design patterns for simplifying functions with many parameters.

Good reference example: https://github.com/DHI/modelskill/discussions/492 — the `scatter()` function has grown a long signature:

```python
def scatter(
x: np.ndarray,
y: np.ndarray,
*,
bins: int | float = 120,
quantiles: int | Sequence[float] | None = None,
fit_to_quantiles: bool = False,
show_points: bool | int | float | None = None,
show_hist: Optional[bool] = None,
show_density: Optional[bool] = None,
norm: Optional[colors.Normalize] = None,
backend: Literal["matplotlib", "plotly"] = "matplotlib",
figsize: Tuple[float, float] = (8, 8),
xlim: Optional[Tuple[float, float]] = None,
ylim: Optional[Tuple[float, float]] = None,
reg_method: str | bool = "ols",
title: str = "",
xlabel: str = "",
ylabel: str = "",
skill_table: Optional[str | Sequence[str] | Mapping[str, str] | bool] = False,
skill_scores: Mapping[str, float] | None = None,
skill_score_unit: Optional[str] = "",
ax: Optional[Axes] = None,
**kwargs,
) -> Axes:
```

### Alternative patterns to simplify

**1. Fluent interface (method chaining)**

Each component gets its own method. Easy to add/remove parts.

```python
(Comparer(x, y)
.plot()
.scatter(alpha=0.5)
.qq([0.05, 0.5, 0.75, 0.95])
# .reg_line(equation=True)
.skill_table(("n", "bias"))
).show()
```

**2. Configuration objects (dataclasses)**

Group related parameters into typed config objects.

```python
@dataclass
class ScatterStyle:
bins: int = 120
show_points: bool = True
show_density: bool = False
norm: colors.Normalize | None = None

@dataclass
class Layout:
figsize: tuple[float, float] = (8, 8)
xlim: tuple[float, float] | None = None
ylim: tuple[float, float] | None = None
title: str = ""
xlabel: str = ""
ylabel: str = ""

scatter(x, y, style=ScatterStyle(bins=50), layout=Layout(title="My plot"))
```

**3. Presets / named styles**

Offer common configurations as named presets, with overrides.

```python
scatter(x, y, preset="minimal") # just points + 1:1 line
scatter(x, y, preset="full") # density + qq + regression + skill table
scatter(x, y, preset="presentation") # large fonts, clean layout
scatter(x, y, preset="minimal", title="Hm0") # preset + override
```

**4. Composition of small functions**

Instead of one function that does everything, provide building blocks that work with a standard Axes.

```python
fig, ax = plt.subplots()
plot_scatter(ax, x, y, show_density=True)
plot_qq(ax, x, y, quantiles=[0.25, 0.5, 0.75])
plot_reg_line(ax, x, y)
add_skill_table(ax, x, y, metrics=["bias", "rmse"])
```

Each pattern has trade-offs worth discussing: discoverability, type safety, composability, backwards compatibility, learning curve.

Relevant topics: method chaining, `Self` return type, builder pattern, dataclasses as config, API design trade-offs.

コントリビューションガイド

このリポジトリのコントリビューションガイドは索引されていません

調査の方向性

No target file or existing exercise is named. Start by locating the course section where API design or plotting examples are taught, then review its format and neighboring lessons. Done means adding a teaching section or exercise that presents the listed patterns and their discoverability, type-safety, composability, compatibility, and learning-curve trade-offs.

索引モデルが issue の本文から書いたものです。

評価

技術スタック
python
領域
documentation
issue の種類
ドキュメント
難易度
3/5
見積もり時間
1〜2日
活発さ
停滞
明瞭さ
おおむね明確
初心者へのやさしさ
48/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。