Remove explicit default parameter from CTable.add_column. Fixes #631.

Author: FrancescAlted

doc/getting_started/tutorials/13.ctable-basics.ipynb

@@ -1526,7 +1526,7 @@
    ],
    "source": [
     "# Add a 'feels_like' column: temperature adjusted for wind chill (simplified)\n",
-    "climate.add_column(\"feels_like\", blosc2.float32(), default=0.0)\n",
+    "climate.add_column(\"feels_like\", blosc2.field(blosc2.float32(), default=0.0))\n",
     "\n",
     "temp = climate.temperature[:]\n",
     "wind = climate[\"wind_speed\"][:]\n",

examples/ctable/mutations.py

@@ -53,7 +53,7 @@ class Employee:
 print(t)
 
 # -- add_column(): new column filled with a default -------------------------
-t.add_column("bonus", blosc2.float64(ge=0), default=0.0)
+t.add_column("bonus", blosc2.field(blosc2.float64(ge=0), default=0.0))
 print("After add_column('bonus'):")
 print(t)
 

src/blosc2/ctable.py

@@ -13,6 +13,7 @@
 import ast
 import contextlib
 import contextvars
+import copy
 import dataclasses
 import itertools
 import os
@@ -68,6 +69,7 @@
     _validate_column_name,
     compile_schema,
     compute_display_width,
+    get_blosc2_field_metadata,
     schema_from_dict,
     schema_to_dict,
 )
@@ -3688,32 +3690,60 @@ def from_csv(
     # Schema mutations: add / drop / rename columns
     # ------------------------------------------------------------------
 
+    @staticmethod
+    def _column_spec_default_and_cparams(
+        spec_or_field: SchemaSpec | dataclasses.Field,
+    ) -> tuple[SchemaSpec, Any, dict | None]:
+        """Extract the schema spec, default and cparams for ``add_column()``."""
+        if isinstance(spec_or_field, dataclasses.Field):
+            meta = get_blosc2_field_metadata(spec_or_field)
+            if meta is None:
+                raise TypeError("add_column() field descriptors must be created with blosc2.field().")
+            spec = copy.deepcopy(meta["spec"])
+            if spec_or_field.default is not MISSING:
+                default = spec_or_field.default
+            elif spec_or_field.default_factory is not MISSING:  # type: ignore[misc]
+                default = spec_or_field.default_factory()
+            else:
+                default = MISSING
+            cparams = meta.get("cparams")
+        else:
+            spec = spec_or_field
+            default = MISSING
+            cparams = None
+
+        if not isinstance(spec, SchemaSpec):
+            raise TypeError(f"add_column() requires a SchemaSpec, got {type(spec)!r}.")
+        return spec, default, cparams
+
     def add_column(
         self,
         name: str,
-        spec: SchemaSpec,
-        default,
+        spec: SchemaSpec | dataclasses.Field,
         *,
         cparams: dict | None = None,
     ) -> None:
-        """Add a new column filled with *default* for every existing live row.
+        """Add a new column filled from the default declared in *spec*.
 
         Parameters
         ----------
         name:
             Column name.  Must follow the same naming rules as schema fields.
         spec:
-            A schema descriptor such as ``b2.int64(ge=0)`` or ``b2.string()``.
-        default:
-            Value written to every existing live row.  Must be coercible to
-            *spec*'s dtype.
+            A schema descriptor such as ``b2.int64(ge=0)`` or a field
+            descriptor such as ``b2.field(b2.int64(ge=0), default=0)``.
+            A default is required when the table already has live rows, so
+            those rows can be backfilled.
         cparams:
-            Optional compression parameters for this column's NDArray.
+            Optional compression parameters for this column's NDArray.  When
+            *spec* is a :func:`blosc2.field` descriptor, its compression
+            parameters are used unless this argument is provided.
 
         Raises
         ------
         ValueError
-            If the table is read-only, is a view, or the column already exists.
+            If the table is read-only, is a view, the column already exists,
+            or a non-empty table is given a column without a default value.
         TypeError
             If *default* cannot be coerced to *spec*'s dtype.
         """
@@ -3727,6 +3757,17 @@ def add_column(
         if name in self._computed_cols:
             raise ValueError(f"A computed column named {name!r} already exists.")
 
+        spec, default, field_cparams = self._column_spec_default_and_cparams(spec)
+        if cparams is None:
+            cparams = field_cparams
+
+        live_pos = np.where(self._valid_rows[:])[0]
+        if default is MISSING and len(live_pos) > 0:
+            raise ValueError(
+                "add_column() requires a default declared as blosc2.field(..., default=...) "
+                "when the table has live rows."
+            )
+
         compiled_col = self._compiled_column_from_spec(name, spec)
         self._resolve_nullable_specs(
             CompiledSchema(row_cls=None, columns=[compiled_col], columns_by_name={name: compiled_col}),
@@ -3737,7 +3778,6 @@ def add_column(
         if self._is_varlen_scalar_column(compiled_col):
             # Varlen scalar columns don't use fixed-width NDArray storage.
             new_col = self._storage.create_varlen_scalar_column(name, spec=spec, cparams=cparams)
-            live_pos = np.where(self._valid_rows[:])[0]
             for _ in live_pos:
                 new_col.append(default)
             new_col.flush()
@@ -3746,10 +3786,15 @@ def add_column(
                 "add_column() does not support list columns; use the constructor with a full schema."
             )
         else:
-            try:
-                default_val = spec.dtype.type(default)
-            except (ValueError, OverflowError) as exc:
-                raise TypeError(f"Cannot coerce default {default!r} to dtype {spec.dtype!r}: {exc}") from exc
+            if default is not MISSING:
+                try:
+                    default_val = spec.dtype.type(default)
+                except (ValueError, OverflowError) as exc:
+                    raise TypeError(
+                        f"Cannot coerce default {default!r} to dtype {spec.dtype!r}: {exc}"
+                    ) from exc
+            else:
+                default_val = None
 
             capacity = len(self._valid_rows)
             default_chunks, default_blocks = compute_chunks_blocks((capacity,))
@@ -3762,7 +3807,6 @@ def add_column(
                 cparams=cparams,
                 dparams=None,
             )
-            live_pos = np.where(self._valid_rows[:])[0]
             if len(live_pos) > 0:
                 new_col[live_pos] = default_val
 

tests/ctable/test_ctable_computed_cols.py

@@ -376,7 +376,7 @@ def test_add_stored_collision_with_computed():
     t = _make_invoice_table()
     t.add_computed_column("total", lambda cols: cols["price"] * cols["qty"])
     with pytest.raises(ValueError, match="already exists"):
-        t.add_column("total", blosc2.float64(), default=0.0)
+        t.add_column("total", blosc2.field(blosc2.float64(), default=0.0))
 
 
 # ---------------------------------------------------------------------------

tests/ctable/test_nullable.py

@@ -147,7 +147,7 @@ class Row:
 def test_add_column_nullable_true_uses_null_policy():
     t = CTable(IntRow)
     with blosc2.null_policy(blosc2.NullPolicy(signed_int_strategy="max")):
-        t.add_column("extra", blosc2.int32(nullable=True), 0)
+        t.add_column("extra", blosc2.field(blosc2.int32(nullable=True), default=0))
 
     assert t["extra"].null_value == np.iinfo(np.int32).max
 

tests/ctable/test_schema_mutations.py

@@ -203,34 +203,47 @@ def test_assign_respects_deleted_rows():
 
 def test_add_column_appears_in_col_names():
     t = CTable(Row, new_data=DATA10)
-    t.add_column("weight", blosc2.float64(), 0.0)
+    t.add_column("weight", blosc2.field(blosc2.float64(), default=0.0))
     assert "weight" in t.col_names
 
 
 def test_add_column_fills_default_for_existing_rows():
     t = CTable(Row, new_data=DATA10)
-    t.add_column("weight", blosc2.float64(), 5.5)
+    t.add_column("weight", blosc2.field(blosc2.float64(), default=5.5))
     np.testing.assert_array_equal(t["weight"][:], np.full(10, 5.5))
 
 
+def test_add_column_without_default_allowed_for_empty_table():
+    t = CTable(Row)
+    t.add_column("weight", blosc2.float64())
+    t.append((1, 2.0, True, 3.0))
+    assert t["weight"][0] == pytest.approx(3.0)
+
+
+def test_add_column_without_default_on_non_empty_table_raises():
+    t = CTable(Row, new_data=DATA10)
+    with pytest.raises(ValueError, match="requires a default"):
+        t.add_column("weight", blosc2.float64())
+
+
 def test_add_column_new_rows_can_use_it():
     t = CTable(Row, new_data=DATA10)
-    t.add_column("weight", blosc2.float64(), 0.0)
+    t.add_column("weight", blosc2.field(blosc2.float64(), default=0.0))
     # After adding, extend doesn't know about weight — add manually
     t["weight"].assign(np.ones(10) * 2.0)
     assert t["weight"].mean() == pytest.approx(2.0)
 
 
 def test_add_column_schema_updated():
     t = CTable(Row, new_data=DATA10)
-    t.add_column("weight", blosc2.float64(), 0.0)
+    t.add_column("weight", blosc2.field(blosc2.float64(), default=0.0))
     assert "weight" in t.schema.columns_by_name
 
 
 def test_add_column_persists_on_disk():
     path = table_path("add_col")
     t = CTable(Row, urlpath=path, mode="w", new_data=DATA10)
-    t.add_column("weight", blosc2.float64(), 7.0)
+    t.add_column("weight", blosc2.field(blosc2.float64(), default=7.0))
     t.close()
     t2 = CTable.open(path)
     assert "weight" in t2.col_names
@@ -241,25 +254,25 @@ def test_add_column_view_raises():
     t = CTable(Row, new_data=DATA10)
     view = t.where(t["id"] > 4)
     with pytest.raises(ValueError, match="view"):
-        view.add_column("weight", blosc2.float64(), 0.0)
+        view.add_column("weight", blosc2.field(blosc2.float64(), default=0.0))
 
 
 def test_add_column_duplicate_raises():
     t = CTable(Row, new_data=DATA10)
     with pytest.raises(ValueError, match="already exists"):
-        t.add_column("score", blosc2.float64(), 0.0)
+        t.add_column("score", blosc2.field(blosc2.float64(), default=0.0))
 
 
 def test_add_column_bad_default_raises():
     t = CTable(Row, new_data=DATA10)
     with pytest.raises(TypeError):
-        t.add_column("flag", blosc2.int8(), "not_a_number")
+        t.add_column("flag", blosc2.field(blosc2.int8(), default="not_a_number"))
 
 
 def test_add_column_skips_deleted_rows():
     t = CTable(Row, new_data=DATA10)
     t.delete([0, 1])  # 8 live rows
-    t.add_column("weight", blosc2.float64(), 3.0)
+    t.add_column("weight", blosc2.field(blosc2.float64(), default=3.0))
     vals = t["weight"][:]
     assert len(vals) == 8
     assert all(v == 3.0 for v in vals)

tests/ctable/test_vlstring_vlbytes.py

@@ -539,7 +539,7 @@ class SimpleRow:
 
 def test_ctable_add_vlstring_column():
     ct = blosc2.CTable(SimpleRow, new_data=[(i,) for i in range(5)])
-    ct.add_column("label", blosc2.vlstring(), default="unknown")
+    ct.add_column("label", blosc2.field(blosc2.vlstring(), default="unknown"))
     assert "label" in ct.col_names
     assert ct.label[0] == "unknown"
     assert ct.label[4] == "unknown"