Ticket #13109: trac_13109-documentation.v2.patch

File trac_13109-documentation.v2.patch, 3.5 KB (added by jhpalmieri, 8 years ago)
  • doc/en/developer/coding_in_python.rst

    # HG changeset patch
    # User Volker Braun <vbraun@stp.dias.ie>
    # Date 1339770473 -3600
    # Node ID 6baa405ba0749c2d0ed59177150fbf7aa66d1e14
    # Parent  bc98aff3a7b2e83d1305d02d9c9f836af70aeefa
    Add a section about deprecation to the developer guide
    
    diff --git a/doc/en/developer/coding_in_python.rst b/doc/en/developer/coding_in_python.rst
    a b possible, since this is what dominates t 
    474474controlling the top-level imports helps to do this.
    475475
    476476
     477Deprecation
     478===========
     479
     480Sooner or later you will find places in the Sage library that are, in
     481hindsight, not designed as well as they could be. Of course you want
     482to improve the overall state, but at the same time we don't want to
     483pull out the carpet under our users' feet. The process of removing old
     484code is called deprecation.
     485
     486.. note::
     487
     488    Before removing any functionality, you should keep a deprecation
     489    warning in place for at least one year (if possible). The
     490    deprecation must include the trac ticket number where it was
     491    introduced.
     492
     493For example, let's say you run across the following while working on a
     494module in the Sage library::
     495
     496    class Foo(SageObject):
     497        def terrible_idea(self):
     498            return 1
     499        def bad_name(self):
     500            return 1
     501        def f(self, weird_keyword=True):
     502            return 1
     503
     504You note that the ``terrible_idea()`` method does not make any sense,
     505and should be removed altogether. You open the trac ticket number 3333
     506(say), and replace the code with::
     507
     508        def terrible_idea(self):
     509            from sage.misc.superseded import deprecation
     510            deprecation(3333, 'You can just call f() instead')
     511            return 1
     512
     513Later, you come up with a much better name for the second method. You
     514open the trac ticket number 4444, and replace it with::
     515
     516        def much_better_name(self):
     517            return 1
     518
     519        bad_name = deprecated_function_alias(4444, much_better_name)
     520
     521Finally, you like the ``f()`` method name but you don't like the
     522``weird_keyword`` name. You fix this by opening the trac ticket 5555,
     523and replacing it with::
     524
     525        @rename_keyword(deprecation=5555, weird_keyword='nice_keyword')
     526        def f(self, nice_keyword=True):
     527            return 1
     528
     529With all necessary imports, the final result looks like this::
     530
     531    from sage.misc.superseded import deprecation, deprecated_function_alias
     532    from sage.misc.decorators import rename_keyword
     533
     534    class Foo(SageObject):
     535
     536        def terrible_idea(self):
     537            deprecation(3333, 'You can just call f() instead')
     538            return 1
     539
     540        def much_better_name(self):
     541            return 1
     542
     543        bad_name = deprecated_function_alias(4444, much_better_name)
     544
     545        @rename_keyword(deprecation=5555, weird_keyword='nice_keyword')
     546        def f(self, nice_keyword=True):
     547            return 1
     548
     549Now, any user that still relies on the deprecated functionality will
     550be informed that this is about to change, yet the deprecated commands
     551still work::
     552
     553    sage: foo = Foo()
     554    sage: foo.terrible_idea()
     555    DeprecationWarning: You can just call f() instead
     556    See http://trac.sagemath.org/3333 for details.
     557    1
     558
     559    sage: foo.bad_name()
     560    DeprecationWarning: bad_name is deprecated. Please use much_better_name instead.
     561    See http://trac.sagemath.org/4444 for details.
     562    1
     563
     564    sage: foo.f(weird_keyword=False)
     565    DeprecationWarning: use the option 'nice_keyword' instead of 'weird_keyword'
     566    See http://trac.sagemath.org/5555 for details.
     567    1
     568 
     569
    477570Editing existing files
    478571======================
    479572