On Jan 24, 2008, at 11:20 AM, William Stein wrote:
> 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.
I think that, when it's easy to do, it makes sense to throw an error
for x number of months/releases/?. Something like
def adjacency_matrix(self, base_ring=ZZ, over_integers=DEPRECATED):
if over_integers != DEPRECATED:
raise DepricatedError, "Use base_ring=ZZ rather than
over_integers=bool"
which would be in addition to a tag in the docstring. One could
easily search for DEPRECATED (which would be a constant somewhere, or
we could just use the string 'DEPRECATED') before a major release to
decide which, if any, are now safe to remove. I think doctesting for
this error is overkill, but I guess one could if one wants.
> 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.
+1 to the idea of a DEPRECATED tag. People will actually write and
read those.
- Robert
--~--~---------~--~----~------------~-------~--~----~
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
-~----------~----~----~----~------~----~------~--~---
