Deprecation for private and semi-private callables

[kryzar]

Problem Description

The Developer Guide, Section Deprecation does not specify if the deprecation process applies to semi-private (name starts with exactly one underscore) or private (name starts with exactly two underscores) callables (functions, methods, attributes, classes, etc).

Proposed Solution

I think the following two options are both valid:

• Semi-private or private methods are for devs and are not part of the interface; users should not use them, which is a Python-wide convention, and the devs should not have to worry about keeping compatibility for semi-private and private callables.

• However, it seems the developer guide deprecation process applies to those as well, and not all users are aware of the _ and __ convention.

Both options are fine to me and I believe this is a minor issue. However, I think the community should pick a single approach and make it somewhat official but explicitly putting it in the developer guide.

Alternatives Considered

See above.

Additional Information

No response

Is there an existing issue for this?

• I have searched the existing issues for a bug report that matches the one I want to file, without success.

[grhkm21]

@mkoeppe @tscrim @kwankyu Pinging you three because of the discussion on my PR, also about deprecating things.

Travis has commented in the past on my other PR that semi-private and private methods indeed do not go through the deprecation process, but other developers are saying I'm cherry-picking comments, so writing this down somewhere concrete would be better.

[kwankyu]

To avoid further confusion, let's try to settle down this issue. Continuing the discussion from #38207, I suggest:

The deprecation policy means what is described in https://doc.sagemath.org/html/en/developer/coding_in_python.html#deprecation.

We want to clarify the policy with the following details:

(S) Only the definitions of functions/methods/attributes/classes living under sage. are subject to the deprecation policy.
(M) A function/method/attribute whose name starts with one or more underscores are considered internal, and is not subject to the deprecation policy.
(C) A class whose name has an underscore anywhere is internal, and is not subject to the deprecation policy.
(E) Experimental code following https://doc.sagemath.org/html/en/developer/coding_in_python.html#experimental-unstable-code is not subject to the deprecation policy.

More suggestions? Missing cases?

[kryzar]

Sounds good to me. Maybe some examples could be provided in the dev. guide.

EDIT: Stroke my comment after the next two comments.

[roed314]

I worry that (C) is too permissive. For example, NumberField_quadratic has an underscore; I think it's fairly common in the Sage codebase to use underscores to divide sections of a name.

Is there an example of a class that you think should be considered internal?

[dimpase]

I worry that (C) is too permissive. For example, NumberField_quadratic has an underscore; I think it's fairly common in the Sage codebase to use underscores to divide sections of a name.

indeed, (C) should not happen.

Is there an example of a class that you think should be considered internal?

[kwankyu]

For example, NumberField_quadratic has an underscore; I think it's fairly common in the Sage codebase to use underscores to divide sections of a name.

Right. Then do you think that NumberField_quadratic is in public API? So that if you would change NumberField_quadratic to NumberField_quadratic_extension, NumberField_quadratic should be subject to the deprecation policy?

If you think so, would you suggest a replacement of (C)?

Or do you think any class name (starting with a letter other than an underscore) change should be subject to the deprecation policy?

[mkoeppe]

For example, NumberField_quadratic has an underscore;

Yes, this is a good example for this discussion. NumberField_quadratic an implementation class, and it is not necessary to have it in the public API.

The public API to create a number field is through the sage.rings.number_field.number_field.NumberField factory function.
And a way to check whether an object K is a quadratic number field using only public API is to use isinstance(K, sage.rings.number_field.number_field_base.NumberField) and K.base_field() == QQ and K.degree() == 2.

[roed314]

Does the deprecation policy apply only to renaming the class, or also to changing methods on it? I agree that it's probably fine to rename NumberField_quadratic to NumberField_quadratic_extension; it's not a good idea to be able to modify methods on it at will just because this class is considered "internal."

[mkoeppe]

Users should certainly be able to rely on the interface of public methods of objects that have been constructed using public API.

[saraedum]

I'm not opposed to the proposal but just for the record, these classes are in sage.all and contain an underscore:

['Berkovich_Cp_Affine',
 'Berkovich_Cp_Projective',
 'DynamicalSemigroup_affine',
 'DynamicalSemigroup_projective',
 'DynamicalSystem_Berkovich',
 'DynamicalSystem_affine',
 'DynamicalSystem_product_projective',
 'DynamicalSystem_projective',
 'Euler_Phi',
 'GroupExp_Class',
 'PermutationGroupMorphism_id',
 'PermutationGroupMorphism_im_gens',
 'PermutationGroup_generic',
 'PermutationGroup_subgroup',
 'Riemann_Map']

[kwankyu]

If we adopt (C), then this gives a clear reason to choose either one of QuadraticNumberField (public) and NumberField_quadratic (internal) to name a class implementing quadratic number fields.

Moreover after adopting (C), if one wants to make a public version out of NumberField_quadratic, then he can just rename it to QuadraticNumberField without deprecation warning :-)