Opened 15 months ago

Last modified 8 weeks ago

#25383 new enhancement

deprecate useless or misleading functions in the global namespace [a-f]

Reported by: vdelecroix Owned by:
Priority: major Milestone: sage-8.4
Component: misc Keywords:
Cc: tmonteil Merged in:
Authors: Vincent Delecroix Reviewers:
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Description (last modified by chapoton)

Cryptic

  • addgp
  • benchmark

Too specific

  • absolute_igusa_invariants_kohel #28064
  • absolute_igusa_invariants_wamelen #28064
  • all_max_clique (should be a method of a graph. Done in #26200)
  • backtrack_all (for sudoku) #27066
  • berlekamp_massey #27066
  • bernoulli_mod_p
  • bernoulli_mod_p_single
  • branching_rule (done in #25791)
  • branching_rule_from_plethysm (done in #25791)
  • bsgs (baby step giant step, done in #25383)
  • build_alphabet
  • buzzard_tpslopes #27066
  • clebsch_gordan
  • clebsch_invariants #28064
  • clique_number (done in #26200)
  • cm_j_invariants
  • cm_j_invariants_and_orders
  • cm_orders
  • coercion_traceback
  • coincidence_discriminant
  • coincidence_index
  • continuant
  • convergents -> continued_fraction(x).convergents() #27066
  • cremona_curves
  • cremona_optimal_curves
  • cunningham_prime_factors
  • cython_create_local_so
  • delta_lseries
  • delta_qexp
  • designs_from_XML #27066
  • designs_from_XML_url #27066
  • dimension_cusp_forms
  • dimension_eis
  • dimension_modular_forms
  • dimension_new_cusp_forms
  • dimension_supersingular_module
  • direct_product_permgroups
  • discrete_log_generic, discrete_log_lambda, discrete_log_rho
  • eisenstein_series_lseries
  • eisenstein_series_qexp
  • enum_affine_finite_field
  • enum_affine_rational_field
  • enumerate_totallyreal_fields_all
  • enumerate_totallyreal_fields_prim
  • enumerate_totallyreal_fields_rel
  • eta_poly_relations #26196
  • eulers_method, eulers_method_2x2 and eulers_method_2x2_plot are accessible via desolvers.
  • exists_conway_polynomial
  • explain_pickle
  • expnums ?
  • extend_to_primitive
  • external_ray
  • find_a_ternary_qf_by_level_disc
  • find_all_ternary_qf_by_level_disc
  • firing_graph
  • four_squares
  • frequency_distribution
  • fundamental_discriminant

Shortcut f(x) -> x.f():

  • additive_order
  • base_ring
  • base_field
  • basis
  • canonical_coercion -> coercion_model.canonical_coercion
  • matrices (block_matrix, block_diagonal_matrix, column_matrix, companion_matrix, diagonal_matrix, ...) can be accessed with matrix.block, matrix.block_diagonal, etc
  • decomposition
  • denominator, numerator
  • desolve, desolve_laplace, desolve_mintides, etc -> desolvers.XXX

WTF

  • absolute_import (nothing to do here)
  • abstract_method (nothing to do in the global namespace)
  • addition_names (a useless tuple)
  • alarm (nothing to do here)
  • attrcall (nothing to do here)
  • banner (no reason to have it in the global namespace)
  • cancel_alarm
  • class_graph
  • db, db_save (what is the Sage database?)
  • degree_lowest_rational_function
  • differences
  • eratosthenes

Change History (31)

comment:1 Changed 15 months ago by vdelecroix

  • Description modified (diff)

comment:2 Changed 15 months ago by jdemeyer

I'm not entirely sure that banner is unused. I can see that being actually used somewhere as from sage.all import banner. Although deprecating it cannot hurt.

The rest should be no problem.

Last edited 15 months ago by jdemeyer (previous) (diff)

comment:3 Changed 15 months ago by vdelecroix

  • Cc tmonteil added

comment:4 Changed 15 months ago by vdelecroix

  • Description modified (diff)

comment:5 Changed 15 months ago by vdelecroix

  • Description modified (diff)
  • Summary changed from deprecate useless or misleading functions in the global namespace to deprecate useless or misleading functions in the global namespace [a-f]

comment:6 follow-up: Changed 15 months ago by kcrisman

Sage did actually have some proto-database functionality but that never really went very far.

I'm not sure that desolve should move; similarly with the various types of matrices. In a lot of contexts you really want the absolutely easiest dumb-sounding command, and extra object-oriented stuff can be confusing there.

That said, most of these probably indeed are a bit specific for top-level. Seems like the kind of thing to put on sage-devel and allow people to ask for things to be separately discussed if necessary: see e.g. consent agendas.

comment:7 follow-up: Changed 15 months ago by jdemeyer

What's wrong with alarm and column_matrix? (just picking two which look genuinely useful)

comment:8 in reply to: ↑ 7 Changed 15 months ago by vdelecroix

Replying to jdemeyer:

What's wrong with alarm and column_matrix? (just picking two which look genuinely useful)

This is not a strong opinion. I just made up a list by quickly looking at dir(). Concerning the two names you mention:

  • what is alarm useful for for a Sage user that does not know how to import it?
  • column_matrix is accessible via matrix.column and I believe it is easier (if properly advertised) to use the second version

Removing from the global namespace is different from removing.

comment:9 in reply to: ↑ 6 ; follow-up: Changed 15 months ago by vdelecroix

Replying to kcrisman:

Thanks for your comment! I am just trying to make clear that we are at a point where the global namespace is so confusing that it is impossible to find anything relevant. What should be kept and how it should be organized is definitely open to suggestion. But I am not sure that discussing one by one the entries on this ticket is the best strategy.

Sage did actually have some proto-database functionality but that never really went very far.

I'm not sure that desolve should move; similarly with the various types of matrices. In a lot of contexts you really want the absolutely easiest dumb-sounding command, and extra object-oriented stuff can be confusing there.

That said, most of these probably indeed are a bit specific for top-level. Seems like the kind of thing to put on sage-devel and allow people to ask for things to be separately discussed if necessary: see e.g. consent agendas.

I was thinking of something like this. It is very likely that commands will be moved by small amount in separate tickets.

comment:10 in reply to: ↑ 9 ; follow-up: Changed 14 months ago by nbruin

Replying to vdelecroix:

Thanks for your comment! I am just trying to make clear that we are at a point where the global namespace is so confusing that it is impossible to find anything relevant. What should be kept and how it should be organized is definitely open to suggestion. But I am not sure that discussing one by one the entries on this ticket is the best strategy.

In what way is the global namespace "confusing"? Is it hard for python to find the bindings? (no because python dictionaries should basically have access time independent of the size of the dictionary)

Is the problem that browsing the global namespace gives too long a list? It may just be the case that browsing the global namespace is not such a great strategy to learn about a computer algebra system.

I think some culling can definitely be done, but the change has a cost, so I think it should be justified. What benefit do we get from culling?

comment:11 in reply to: ↑ 10 ; follow-up: Changed 14 months ago by vdelecroix

Replying to nbruin:

Replying to vdelecroix:

Thanks for your comment! I am just trying to make clear that we are at a point where the global namespace is so confusing that it is impossible to find anything relevant. What should be kept and how it should be organized is definitely open to suggestion. But I am not sure that discussing one by one the entries on this ticket is the best strategy.

In what way is the global namespace "confusing"? Is it hard for python to find the bindings? (no because python dictionaries should basically have access time independent of the size of the dictionary)

Indeed, nobody cares about this.

Is the problem that browsing the global namespace gives too long a list? It may just be the case that browsing the global namespace is not such a great strategy to learn about a computer algebra system.

The length is not so important. The problem is that you have access to so many specialized and/or useless functions. If the functions/classes were better organized by modules (for example graphs.<TAB> is cool) it would be simpler to find functionalities. The only reasonable strategies I know for searching for a functionality in Sage is the tab-completion and grepping the source. While the latter technique is powerful it is not ideal for a newcomer. The Sage documentation could have been an alternative but it is very bad at the moment. The only references I know where things are organized are the books written about Sage (e.g. "Calcul Mathématique avec Sage" by Zimmermann et al.)

So it is not about learning but about searching. I am focusing not on the newcomers, but the next stage (learners?). The problem is "I want to do that, how do I do"?

I think some culling can definitely be done, but the change has a cost, so I think it should be justified. What benefit do we get from culling?

Cost for the developer? Cost for the reviewer? Cost for the one person who uses an ultra specialized feature that is imported by default?

comment:12 Changed 14 months ago by jhpalmieri

We also advertise tab-completion in the tutorial (and probably other places) as a way to learn about the system, and so perhaps the length of the list may actually be an issue.

comment:13 Changed 14 months ago by dcoudert

I agree that methods like:

  • random_DAG, firing_graph, parallel_firing_graph defined in sandpile/ could be moved to digraphs.<TAB>
  • all_max_clique, clique_number, max_clique should be methods of Graph only.

Questions:

  • how to know where a method is defined ? For instance, when typing random_DAG? I don't get the source file of the method but of LazyImport.
  • Is there an easy way to know where a method is used ? I'm usually relying on grep which might not be the smartest way.

comment:14 Changed 14 months ago by vdelecroix

This works often

sage: import_statements(random_DAG)
from sage.sandpiles.sandpile import random_DAG

and this as well

sage: import_statements("random_DAG")
from sage.sandpiles.sandpile import random_DAG

comment:15 Changed 14 months ago by dcoudert

Thanks ! I'm learning every day ;)

comment:16 in reply to: ↑ 11 Changed 14 months ago by nbruin

Replying to vdelecroix:

The length is not so important. The problem is that you have access to so many specialized and/or useless functions. If the functions/classes were better organized by modules (for example graphs.<TAB> is cool) it would be simpler to find functionalities.

I've tried that occasionally (not particularly on graphs) and have been underwhelmed with the results. Namespaces in python are generally too cluttered to be useful in that way (plus, the standard IPython interfaces give the completion list in a very small window, without much additional information). I have generally resorted to using "google" to get a hold of some relevant documentation. Once I have an object that is probably related to the functionality I'm looking for, I'd generally use a bit of tab completion on that (and wade through all the boiler-plate infrastructure that's cluttering those results)

If we'd have a command that would print a list such that you can hover over the results to see the associated docstring, I think it would already be a lot more useful. Especially if clicking would then redirect to the HTML documentation.

The only reasonable strategies I know for searching for a functionality in Sage is the tab-completion and grepping the source. While the latter technique is powerful it is not ideal for a newcomer. The Sage documentation could have been an alternative but it is very bad at the moment. The only references I know where things are organized are the books written about Sage (e.g. "Calcul Mathématique avec Sage" by Zimmermann et al.)

Indeed, and for "cost" about changing namespace contents, I think such books suffer particularly. Any books/ articles / documentation / scripts that depend on the contents of certain namespaces are affected by changes. Changing contents of namespaces causes breakage and therefore bears a significant cost.

So it is not about learning but about searching. I am focusing not on the newcomers, but the next stage (learners?). The problem is "I want to do that, how do I do"?

Cost for the developer? Cost for the reviewer? Cost for the one person who uses an ultra specialized feature that is imported by default?

As above: cost in the form of all existing usage/articles breaking. The benefits of a change must really outweigh such costs. As I describe above, I haven't found "tab completion" such an effective way for browsing functionality either, so the benefits don't seem so large at this point.

If we'd have a better browser for module contents, it may be an easier argument to make. The standard nowadays is really "do we provide a search interface that is considerably better than google search?". Using google is a universal strategy, so unless a specific search strategy for finding sage functionality is *considerably* better, people are better off sticking to using google. I'm not so convinced that the sage documentation browsing (via tab or via HTML indices) gets considerably better results than google, so in reality I don't think changes at this point would lead to significant improvements anyway (search_src definitely has advantages if you have a sufficiently specific term, but indeed might not be so suitable for anybody below "expert" level)

Having better documentation and a better way of searching it would definitely be great. I'm not quite sure that culling the global namespace quite gets us there.

(incidentally, I've been quite happy finding explain_pickle right there in the top-level namespace. I have never been disappointed by finding that something was there in the top-level namespace. Having a bloated top-level does go against a general sense of aesthetics, so there's that, but I have trouble justifying that general feeling by practical arguments)

comment:17 Changed 14 months ago by mantepse

I almost exclusively use sage through the emacs interface (in fact, I don't even really know the ipython interface), and having a cleaner top level namespace might be quite helpful there. I have, apart from aesthetics, two reasons:

  • the list of suggestions becomes shorter, so when looking for something, I have less to read or search through, and thus better chances not to miss the needle in the haystack,
  • tab completion has a better chance of working, that is, I have fewer characters to type to get completion.

However, I must say that things are not terribly bad currently. So in case of doubt, I'd leave a particular item in the global name space.

comment:18 Changed 14 months ago by chapoton

some work in #25785

comment:19 Changed 14 months ago by vdelecroix

  • Description modified (diff)

comment:20 Changed 14 months ago by mantepse

class_graph might actually make sense for exploration - I wouldn't know how to discover this utility otherwise. But I don't know.

comment:21 Changed 14 months ago by chapoton

see also #25791 for more work

comment:22 Changed 14 months ago by vdelecroix

  • Description modified (diff)

comment:23 Changed 13 months ago by vdelecroix

  • Milestone changed from sage-8.3 to sage-8.4

update milestone 8.3 -> 8.4

comment:24 Changed 12 months ago by chapoton

  • Description modified (diff)

comment:25 follow-up: Changed 12 months ago by dcoudert

Methods all_max_clique, max_clique and clique_number are imported into the global namespace in file src/sage/graphs/all.py. It contains from sage.graphs.cliquer import *. This can be removed as these methods are all already methods of Graph.

How should we proceed: open a specific ticket for that? add a deprecation warning, but with what message ?

comment:26 in reply to: ↑ 25 Changed 12 months ago by vdelecroix

Replying to dcoudert:

Methods all_max_clique, max_clique and clique_number are imported into the global namespace in file src/sage/graphs/all.py. It contains from sage.graphs.cliquer import *. This can be removed as these methods are all already methods of Graph.

How should we proceed: open a specific ticket for that? add a deprecation warning, but with what message ?

Yes: open a new ticket. And as it was done already for several of the functions, mention the ticket number in the description here.

comment:27 Changed 12 months ago by dcoudert

  • Description modified (diff)

comment:28 Changed 7 months ago by chapoton

  • Description modified (diff)

comment:29 Changed 6 months ago by jhpalmieri

Related: #27337

comment:30 Changed 8 weeks ago by chapoton

  • Description modified (diff)

comment:31 Changed 8 weeks ago by chapoton

  • Description modified (diff)
Note: See TracTickets for help on using tickets.