Document TableRow.replace() ?

[hyanwong]

The most common thing to want to do when using e.g. NodeTable.append() is to want to change one variable, e.g. time. At the moment this requires you to

import dataclasses
node_table.append(dataclasses.replace(row, time=new_val))

Is it worth having the syntactic sugar

node_table.append(row.replace(time=new_val))

to avoid having to import dataclasses and remember the syntax? This could be a lightweight method on a TableRow class, but is it worth duplicating the data class functionality here? I think on balance it might be, especially for newbies to the wonderful world of tree sequences (it might also encourage using .append() instead of .add_row(x, y, z)).

[benjeffery]

As a data point I have typed the second (currently incorrect) version almost every time I've written this piece of code!

[jeromekelleher]

I thought we had done this? As well as Yan's point (which I agree with) I wasn't keen on the long-term API dependency on dataclasses implied by the dataclasses.replace(row, time=new_val)) - if we encourage users to do this, our rows must be dataclasses forever.

[hyanwong]

That's a good point too. Looks like we should just implement it then? Simply this?

def replace(self, **kwargs)
    detaclasses.replace(self, **kwargs)

I don't know what the "/" in the replace docs parameter list is though: https://docs.python.org/3/library/dataclasses.html#dataclasses.replace

[grahamgower]

I don't know what the "/" in the replace docs parameter list is though: https://docs.python.org/3/library/dataclasses.html#dataclasses.replace

That means the first parameter is positional only. I.e., the keyword cannot be used to specify that param.
https://www.python.org/dev/peps/pep-0570/

[benjeffery]

I'm clearly losing my mind as I implemented this already: https://github.com/tskit-dev/tskit/blob/main/python/tskit/util.py#L37

But then I'm sure @hyanwong got an error trying to use .replace on slack the other day?

[hyanwong]

I thought I did too. But it works now. Hmmm.

[hyanwong]

Reopening because I think this should be documented somewhere?