On Jan 24, 2008 10:41 AM, Jason Grout <[EMAIL PROTECTED]> wrote:
>
> Robert Bradshaw wrote:
> > I think the best way to handle deprecation is to throw an error when
> > the (now invalid) command/options are being used. This way any users
> > of the code will know exactly what the problem is, no matter if they
> > wrote it or how deep it is. After a period of time, this error code
> > can be removed.
> >
> > Of course, good documentation is valuable to have too, and not all
> > errors make valid code invalid.
> >
>
>
> +1
>
> Throwing an error seems like the more pythonic way to handle things,
> i.e., throw a DeprecatedError or something. I also like William's idea
> of a short text blurb in the hg log with some sort of sentinal string so
> that compatibility issues could be extracted easily and formatted as a
> quick "upgrading" guide.
>
> How would we throw a DeprecatedError if we remove a function argument?
> If we leave the argument in there, the argument shows up in the function
> signature still (possibly confusing). If we remove the function
> argument, then python throws an error already. I guess the former way
> is the way to handle things, right? And then in the documentation of
> the arguments, put DEPRECATED or something like that.
>
> Throwing an error doesn't account for situations where the function
> returns something different than it used to.
Throwing an error is problematic for the example situations
we discussed above:
-- it's kind of cluttered having extra arguments that don't get used;
I'm reiterating what you just said. Also, this error would have to
be doctested, and that just seems cluttered. More on this below.
-- it doesn't account for my example, where the *behavior* of the function
changed, but the arguments are the same. There's no way to throw an
error if the user "thinks" the function should return one answer, but
returns a different answer.
I think what libraries often do is document changes, then put a time-limited
deprecation message in, which they remove after a certain number of months.
I think I would be OK with that -- clutter is a lot less of a problem when it
has a self-destruct date. To reiterate, I think it would be best if
we do decide
to go with a DEPRECATED error message, that it include a date, and that
after that date the message is removed. The date could be a few months,
a year, whatever -- it just needs to be there. And it should be altogether
optional; a developer should decide based on taste whether a deprecation
exception should be raised.
The easiest solution to this whole problem would be to just have a
DEPRECATED:
stuff
section at the bottom of the docstring, where by convention we list
deprecated behavior. Each item listed there would have a
destruct date -- or even better we could just delete DEPRECATED sections
that according to hg haven't been changed for at least "1 year" (made
up timeframe).
In fact, honestly I'm unhappy with my proposal to put deprecation info in
the hg log and extract it to a file, since it's very unlikely anyone will
actually look at that file when they need it. Better would be DEPRECATED
sections throughout the Sage source code that have destruct dates.
Then we can auto-generated a list of all deprecated behavior just by
searching through the Sage source code. Also, if a person gets confused
or frustrated by how function foo works, typical behavior is to do
foo?
and look at what comes out. This DEPRECATED section would definitely
get seen by people doing that. It could have anything in it, e.g., doctest
examples, text, whatever authors feel is appropriate.
I can tell you from experience that by far the most likely thing to actually
work and that developers will actually start using is a DEPRECATED:
section in the docstrings. It just feels easy to remember and use, and
is free-form enough that it will get used. It also doesn't clutter the API
at all, and can be easily surpresed if desired.
-- William
--~--~---------~--~----~------------~-------~--~----~
To post to this group, send email to sage-devel@googlegroups.com
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at http://groups.google.com/group/sage-devel
URLs: http://www.sagemath.org
-~----------~----~----~----~------~----~------~--~---
