DHI / DHI/python-package-development

Add fluent interface pattern as teaching example

Offen
#36 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
Vorherrschende Sprache
Jupyter Notebook
Sterne
8
Forks
1
Ø Merge
4 Min.
Gemergte PRs (30 T.)
1

Beschreibung

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.

Beitragsleitfaden

Für dieses Repository ist kein Beitragsleitfaden indexiert

Rechercherichtung

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.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
python
Bereich
documentation
Issue-Typ
Dokumentation
Schwierigkeit
3/5
Geschätzter Aufwand
1-2 Tage
Aktivitätsstatus
Veraltet
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
48/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.