Opened 9 years ago

Last modified 9 years ago

#13109 closed enhancement

Rewrite deprecation to use trac ticket numbers — at Version 7

Reported by: vbraun Owned by: mvngu
Priority: major Milestone: sage-5.2
Component: doctest coverage Keywords:
Cc: cremona, kini, was, jason, kcrisman Merged in:
Authors: Volker Braun Reviewers:
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Status badges

Description (last modified by kcrisman)

As discussed on https://groups.google.com/d/topic/sage-devel/I12IeaFlE7g/discussion, change the deprecation function to the new arguments

deprecation(trac_number, message) 

where both arguments are mandatory. Once this code is in Sage, one can deduce every possible thing discussed above in this thread from the trac number. The deprecation warning can produce the URL of the trac ticket.

Analogous changes are made to deprecated_function_alias and deprecated_callable_import. Finally, the @rename_keyword(deprecated="sage version string", ...) decorator is changed to

@rename_keyword(deprecation=<trac_number>, ...)

Apply

This ticket also fixes #8073.

Change History (7)

comment:1 Changed 9 years ago by kcrisman

I just have to say it, please don't hurt me!

Definition:     sage.misc.misc.deprecation(message, version=None)
Docstring:
       Issue a deprecation warning.
    
       INPUT:
    
          * "message" - an explanation why things are deprecated and by
            what it
               should be replaced.
    
          * "version" - (optional) on which version and when the
            deprecation
               occurred. Please put there the version of sage at the time
               of deprecation.

That's incompatible with the current one, as far as I understand the ways optional args with defaults work. So will the syntax for the deprecation function have to be ... deprecated?

comment:2 Changed 9 years ago by vbraun

That depends on whether the barber of Seville shaves himself or not.

comment:3 Changed 9 years ago by vbraun

  • Description modified (diff)

The first patch changes the deprecation syntax. The second adds the trac numbers to all deprecations in the Sage library. The third fixes all doctests.

comment:4 Changed 9 years ago by vbraun

  • Description modified (diff)

comment:5 Changed 9 years ago by vbraun

  • Authors set to Volker Braun
  • Description modified (diff)

The last patch adds documentation to the developer guide.

comment:6 Changed 9 years ago by vbraun

  • Cc cremona kini was jason kcrisman added
  • Status changed from new to needs_review

comment:7 Changed 9 years ago by kcrisman

  • Description modified (diff)

Very comprehensive work.

  • I first have to say that trac_13109_ticket_numbers.patch is extremely impressive. I guess that relieves any concerns about deprecating the deprecation functionality.
  • Do we want to use the :trac: markup anywhere here? Of course, that doesn't show up as nicely in the command line, so perhaps not.
  • So will it be up the end user to determine whether a given item is nearing the end of its deprecation life? I do like that part of #8546. It could be really tedious to check whether a number of things are due. Why not have that as another (optional) argument? Maybe there is a good reason I'm just missing, certainly this syntax is easier for the person writing the code.
  • Also, what happens if Trac goes the way of ... Mercurial for sagenb?
  • I notice that Foo also has terrible doctesting, in addition to having several ill-conceived methods. But in general I really like it - very clear but also not dry.
  • That said, there should be an example of how to doctest the deprecation, because it won't look like what comes out, but rather
    doctest:...: DeprecationWarning: 
    ]}}
      as you know from the presumably tedious work on the doctest patch.
    
Note: See TracTickets for help on using tickets.