gh-112069: Adapt set/frozenset methods to Argument Clinic

[tomasr8]

This is the first to step to making the set object thread-safe in free threading Python. See this PR for reference. As suggested, I am splitting the PR into one which first adds AC support and then a followup PR which adds thread safety.

• Issue: Make set thread-safe in --disable-gil builds #112069

[tomasr8]

@erlend-aasland Is there a way to convert the number functions (like set_sub, etc.) or functions defined on the type itself (like set_repr) or do I leave them as is?

[erlend-aasland]

@erlend-aasland Is there a way to convert the number functions (like set_sub, etc.) or functions defined on the type itself (like set_repr) or do I leave them as is?

You can only adapt PyMemberDef, PyGetSetDef, and Py_tp_new, Py_tp_init C functions. Eventually, we will add support for slots, but for now only __init__ and __new__ are supported.

[erlend-aasland]

See #114258 for clinic support for slots.

[tomasr8]

See #114258 for clinic support for slots.

Thanks for the context! So if I understand correctly some of the tp_ methods will become available in AC at some point. Should I postpone this PR until then or should we merge it now and then revisit the remaining methods later?

[erlend-aasland]

Thanks for the context!

Anytime :)

So if I understand correctly some of the tp_ methods will become available in AC at some point.

That's the plan, yes.

Should I postpone this PR until then or should we merge it now and then revisit the remaining methods later?

We can adapt the slots later.

[erlend-aasland]

@tomasr8, I marked this as a draft while you are working on updating it; mark is as ready for review when you are ready for a new round of reviews.

[erlend-aasland]

The help() diff between main and this PR is now:

--- main.txt	2024-02-08 16:23:15
+++ pr.txt	2024-02-08 16:23:38
@@ -77,7 +77,7 @@
  |      Return value^self.
  |
  |  __sizeof__(self, /)
- |      S.__sizeof__() -> size of S in memory, in bytes
+ |      S.__sizeof__() -> size of S in memory, in bytes.
  |
  |  __sub__(self, value, /)
  |      Return self-value.
@@ -114,17 +114,18 @@
  |  intersection_update(self, /, *others)
  |      Update the set, keeping only elements found in it and all others.
  |
- |  isdisjoint(self, object, /)
+ |  isdisjoint(self, other, /)
  |      Return True if two sets have a null intersection.
  |
- |  issubset(self, object, /)
+ |  issubset(self, other, /)
  |      Report whether another set contains this set.
  |
- |  issuperset(self, object, /)
+ |  issuperset(self, other, /)
  |      Report whether this set contains another set.
  |
  |  pop(self, /)
  |      Remove and return an arbitrary set element.
+ |
  |      Raises KeyError if the set is empty.
  |
  |  remove(self, object, /)
@@ -228,7 +229,7 @@
  |      Return value^self.
  |
  |  __sizeof__(self, /)
- |      S.__sizeof__() -> size of S in memory, in bytes
+ |      S.__sizeof__() -> size of S in memory, in bytes.
  |
  |  __sub__(self, value, /)
  |      Return self-value.
@@ -245,13 +246,13 @@
  |  intersection(self, /, *others)
  |      Return a new set with elements common to the set and all others.
  |
- |  isdisjoint(self, object, /)
+ |  isdisjoint(self, other, /)
  |      Return True if two sets have a null intersection.
  |
- |  issubset(self, object, /)
+ |  issubset(self, other, /)
  |      Report whether another set contains this set.
  |
- |  issuperset(self, object, /)
+ |  issuperset(self, other, /)
  |      Report whether this set contains another set.
  |
  |  symmetric_difference(self, other, /)

There's one case of an added punctuation, and a couple of cases where the new docstring now aligns better with the docs (using other iso. object). IMO, this is acceptable.

[erlend-aasland]

BTW, generated clinic code excluded, the diff is now 1 file changed, 259 insertions(+), 157 deletions(-); nice!

[erlend-aasland]

Thanks! (I'll land this after you've run make regen-clinic)

[tomasr8]

Thanks a lot for your help!

[colesbury]

Thanks @tomasr8 and @erlend-aasland!