Like others, I think consistent naming is a good idea, except when it is
not(...), and the specific details are harder to get right. Thanks to
those who try to improve the Sage API.
One nice advantage of names such as facets_{num,number,count} is
discoverability via tab-completion, especially if the user already knows
the facets() method exists. It happens that IPython supports [1]
glob-style matches such as obj.*abc*?, to find all attributes containing
"abc", but I suppose most people do not use this feature, so it will be
harder to know that n_facets() exists. On the other hand, in Sage,
trying to complete obj.is_* is a good way to start inspecting an object,
so maybe obj.n_* will be a good starting point for "simple" enumerations.
A partial remedy is adding a SEEALSO block in the factes() docstring
referencing n_factes(), assuming users read the docs. If n_facets() is
more efficient than len(facets()), e.g., in time or memory, then it also
merits a mention in the same place.
Regards,
TB
[1]
https://ipython.readthedocs.io/en/stable/interactive/python-ipython-diff.html
On 01/10/2025 10:47, 'Martin R' via sage-devel wrote:
Dear all!
There are now pull requests (see below) that attempt more uniformity. I
think that the following de facto consensus emerged:
1. in general, we keep the old names as aliases, but replace occurences
of the old names also in the codebase
2. we use n_xxx for methods that are used frequently and number_of_xxx
for the rest
Some of the pull requests have already positive review, some I made
"needs: info", because I do not want to make a silly decision. I don't
think that any of them are already merged.
In general, I see two arguments in favour of the pull requests, and one
against:
* it makes it easier for the casual user to remember the method names
* it makes it possible to grep for such methods (as opposed to `nrows`)
* the aliases pollute the name space
The last point implies that we should be careful in choosing the new
method names. For example, I just realize that
Graph.number_of_connected_components might be better just
Graph.n_components. So, please voice your opinion now :-)
A few people (including myself) warn that the old methods should not be
deprecated, even though this might be tempting for better aesthetics.
We have to keep in mind that there is code outside that uses the old
method names which we do not control, and which is run only rarely. For
example, there is a code snippet for almost every statistic in the
findstat database, many of which would be affected in this particular
case. It would be a shame if these would stop working.
Best wishes,
Martin
https://github.com/sagemath/sage/pull/40875
https://github.com/sagemath/sage/pull/40887
https://github.com/sagemath/sage/pull/40914
https://github.com/sagemath/sage/pull/40917
https://github.com/sagemath/sage/pull/40918
https://github.com/sagemath/sage/pull/40932
https://github.com/sagemath/sage/pull/40939
https://github.com/sagemath/sage/pull/40940
https://github.com/sagemath/sage/pull/40941
https://github.com/sagemath/sage/pull/40942
https://github.com/sagemath/sage/pull/40943
On Thursday, 25 September 2025 at 13:42:13 UTC+2 Frédéric Chapoton wrote:
Hello,
I think it will be hard to achieve consistency on this matter.
Unless of course somebody wants to spent the next few years doing
that. Any volunteer ?
(0) I think we should allow "n*" and "n_*" and "number_of_*" only. I
have a preference for "n_*".
(1) My current proposal is to use "n_*" everywhere in geometry/ This
is a small thing, and ready for review.
(2) one could also easily get rid of all "num_*" as there are not so
many. This is just annoying for graphs,
(3) concerning alias versus deprecation, I would prefer to
deprecate. But we can also keep the aliases and let our heirs do the
deprecation.
Frédéric
Le jeudi 25 septembre 2025 à 03:05:30 UTC+2, Kwankyu Lee a écrit :
I regard
"num_xxx", "n_xxx" and "nxxx"
as different abbreviations of "number_of_xxx". So to abbreviate
"number", we are using "num" and "n". I think we should choose
just one. I prefer "n" (and hate "num").
Hence in my opinion, we should keep
(1) "number_of_" like in "number_of_facets"
(2) "n_" like in "n_facets"
(3) "n" like in "ngens"
and use (3) for names that occur very frequently.
Kwankyu
--
You received this message because you are subscribed to the Google
Groups "sage-devel" group.
To unsubscribe from this group and stop receiving emails from it, send
an email to [email protected] <mailto:sage-
[email protected]>.
To view this discussion visit https://groups.google.com/d/msgid/sage-
devel/804af5fd-c14e-4670-ad1c-e7529bd516c1n%40googlegroups.com <https://
groups.google.com/d/msgid/sage-devel/804af5fd-c14e-4670-ad1c-
e7529bd516c1n%40googlegroups.com?utm_medium=email&utm_source=footer>.
--
You received this message because you are subscribed to the Google Groups
"sage-devel" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion visit
https://groups.google.com/d/msgid/sage-devel/c03f2b66-34bd-45aa-93e5-6d178f83a2b2%40gmail.com.
