Ticket #11298: trac11298_singular_standard_options.patch

File trac11298_singular_standard_options.patch, 17.3 KB (added by SimonKing, 11 years ago)

Introspection for sage.misc.decorators.sage_wraps, applied for singular_standard_options. Put decorators into references.

  • doc/en/reference/misc.rst

    # HG changeset patch
    # User Simon King <simon.king@uni-jena.de>
    # Date 1306393520 -7200
    # Node ID 464219404bca397288f605dc64a7beae8fd9616b
    # Parent  d08fc1cce6212546e52f8bf25f69b4711b18da09
    #11298: Improve introspection for sage.misc.decorators.sage_wraps, and use it for (lib)singular_standard_options.
    Put sage.misc.decorators into the reference manual.
    
    diff --git a/doc/en/reference/misc.rst b/doc/en/reference/misc.rst
    a b  
    88
    99   sage/misc/abstract_method
    1010   sage/misc/cachefunc
     11   sage/misc/decorators
    1112   sage/misc/function_mangling
    1213   sage/misc/exceptions
    1314   sage/misc/misc
  • sage/misc/decorators.py

    diff --git a/sage/misc/decorators.py b/sage/misc/decorators.py
    a b  
    66AUTHORS:
    77
    88- Tim Dumol (5 Dec 2009) -- initial version.
    9 - Johan S. R. Nielsen (2010) -- collect decorators from various modules
    10 - Johan S. R. Nielsen (8 apr 2011) -- improve introspection on decorators
     9- Johan S. R. Nielsen (2010) -- collect decorators from various modules.
     10- Johan S. R. Nielsen (8 apr 2011) -- improve introspection on decorators.
     11- Simon King (2011-05-26) -- improve introspection of sage_wraps. Put this
     12  file into the reference manual.
     13
    1114"""
    1215from functools import partial, update_wrapper, WRAPPER_ASSIGNMENTS, WRAPPER_UPDATES
    1316from copy import copy
    14 from sage.misc.sageinspect import sage_getsource
     17from sage.misc.sageinspect import sage_getsource, sage_getsourcelines
    1518from sage.misc.misc import verbose, deprecation
    1619from inspect import ArgSpec
    1720
    1821def sage_wraps(wrapped, assigned = WRAPPER_ASSIGNMENTS, updated = WRAPPER_UPDATES):
    19     """
     22    r"""
    2023    Decorator factory which should be used in decorators for making sure that
    2124    meta-information on the decorated callables are retained through the
    2225    decorator, such that the introspection functions of
     
    3033    the special attribute ``_sage_argspec_`` of the wrapping function (for an
    3134    example, see e.g. ``@options`` decorator in this module).
    3235
    33     EXAMPLES::
     36    EXAMPLES:
    3437
    3538    Demonstrate that documentation string and source are retained from the
    36     decorated function
     39    decorated function::
    3740
    3841        sage: def square(f):
    3942        ...     @sage_wraps(f)
     
    5053        x^2
    5154        sage: g.__doc__
    5255        'My little function'
    53         sage: from sage.misc.sageinspect import sage_getsource
     56        sage: from sage.misc.sageinspect import sage_getsource, sage_getsourcelines, sage_getfile
    5457        sage: sage_getsource(g)
    5558        '@square...def g(x)...'
    5659
    5760    Demonstrate that the argument description are retained from the decorated
    58     function through the special method (when left unchanged) (see trac #9976).
     61    function through the special method (when left unchanged) (see trac #9976)::
    5962
    6063        sage: def diff_arg_dec(f):
    6164        ...     @sage_wraps(f)
     
    7376        sage: sage_getargspec(g)
    7477        ArgSpec(args=['x'], varargs=None, keywords=None, defaults=None)
    7578
     79    Demonstrate that it correctly gets the source lines and the source
     80    file, which is essential for interactive code edition; note that we
     81    do not test the line numbers, as they may easily change::
     82
     83        sage: P.<x,y> = QQ[]
     84        sage: I = P*[x,y]
     85        sage: sage_getfile(I.interreduced_basis)
     86        '...sage/rings/polynomial/multi_polynomial_ideal.py'
     87        sage: sage_getsourcelines(I.interreduced_basis)
     88        (['    @singular_standard_options\n',
     89          '    @libsingular_standard_options\n',
     90          '    def interreduced_basis(self):\n',
     91          ...
     92          '        return ret\n'], ...)
     93
    7694    Demonstrate that sage_wraps works for non-function callables
    77     (Trac 9919)
     95    (Trac 9919)::
    7896
    7997        sage: def square_for_met(f):
    8098        ...     @sage_wraps(f)
     
    99117    def f(wrapper):
    100118        update_wrapper(wrapper, wrapped, assigned=assigned, updated=updated)
    101119        wrapper._sage_src_=lambda: sage_getsource(wrapped)
     120        wrapper._sage_src_lines_=lambda: sage_getsourcelines(wrapped)
    102121        #Getting the signature right in documentation by Sphinx (Trac 9976)
    103122        #The attribute _sage_argspec_() is read by Sphinx if present and used
    104123        #as the argspec of the function instead of using reflection.
    105         from sageinspect import sage_getargspec
     124        from sageinspect import sage_getargspec, sage_getsource
    106125        argspec = sage_getargspec(wrapped)
    107126        wrapper._sage_argspec_ = lambda: argspec
    108127        return wrapper
     
    365384    def __init__(self, name, **options):
    366385        """
    367386        A decorator for functions which collects all keywords
    368         starting with name_ and collects them into a dictionary
     387        starting with ``name+'_'`` and collects them into a dictionary
    369388        which will be passed on to the wrapped function as a
    370         dictionary called name_options.
     389        dictionary called ``name_options``.
    371390
    372391        The keyword arguments passed into the constructor are taken
    373         to be default for the name_options dictionary.
     392        to be default for the ``name_options`` dictionary.
    374393
    375394        EXAMPLES::
    376395
     
    464483            {'rgbcolor': (0, 0, 1)}
    465484
    466485        Demonstrate that the introspected argument specification of the wrapped
    467         function is updated (see trac #9976).
     486        function is updated (see trac #9976)::
    468487
    469488            sage: from sage.misc.decorators import options
    470489            sage: o = options(rgbcolor=(0,0,1))
  • sage/misc/sageinspect.py

    diff --git a/sage/misc/sageinspect.py b/sage/misc/sageinspect.py
    a b  
    13501350        ...
    13511351        '    raise ValueError, "k must be an integer or an integer + 1/2"\n'], 31)
    13521352
    1353     Here are some cases that where covered in trac ticket #11298::
     1353    Here are some cases that where covered in trac ticket #11298;
     1354    note that line numbers may easily change, and therefore we do
     1355    not test them::
    13541356
    13551357        sage: P.<x,y> = QQ[]
    13561358        sage: I = P*[x,y]
     
    13591361          "    def __init__(self, base_ring, n, names, order='degrevlex'):\n",
    13601362        ...
    13611363          '          M.append(new_MP(self, p_Copy(tempvector,_ring)))\n',
    1362           '          return M\n'], 225)
     1364          '          return M\n'], ...)
    13631365        sage: sage_getsourcelines(I)
    13641366        (['class MPolynomialIdeal( MPolynomialIdeal_singular_repr, \\\n',
    13651367        ...
    1366         '        return result_ring.ideal(result)\n'], 2612)
     1368        '        return result_ring.ideal(result)\n'], ...)
    13671369        sage: x = var('x')
    13681370        sage: sage_getsourcelines(x)
    13691371        (['cdef class Expression(CommutativeRingElement):\n',
    13701372          '    cpdef object pyobject(self):\n',
    13711373        ...
    1372           '        return self / x\n'], 191)
     1374          '        return self / x\n'], ...)
    13731375       
    13741376
    13751377    AUTHORS:
  • sage/rings/polynomial/multi_polynomial_ideal.py

    diff --git a/sage/rings/polynomial/multi_polynomial_ideal.py b/sage/rings/polynomial/multi_polynomial_ideal.py
    a b  
    424424            pass
    425425
    426426def singular_standard_options(func):
    427     """
     427    r"""
    428428    Decorator to force a reduced Singular groebner basis.
    429429   
    430430    TESTS::
     
    435435        sage: "buchberger" in sage_getsource(J.interreduced_basis)
    436436        True
    437437
     438    The following tests against a bug that was fixed in trac ticket #11298::
     439
     440        sage: from sage.misc.sageinspect import sage_getsourcelines, sage_getargspec
     441        sage: P.<x,y> = QQ[]
     442        sage: I = P*[x,y]
     443        sage: sage_getargspec(I.interreduced_basis)
     444        ArgSpec(args=['self'], varargs=None, keywords=None, defaults=None)
     445        sage: sage_getsourcelines(I.interreduced_basis)
     446        (['    @singular_standard_options\n',
     447          '    @libsingular_standard_options\n',
     448          '    def interreduced_basis(self):\n',
     449          ...
     450          '        return ret\n'], ...)
     451
    438452    .. note::
    439453
    440454       This decorator is used automatically internally so the user
    441455       does not need to use it manually.
    442456    """
     457    from sage.misc.decorators import sage_wraps
     458    @sage_wraps(func)
    443459    def wrapper(*args, **kwds):
    444         """
    445         Execute function in ``SingularDefaultContext``.
    446         """
     460#        """
     461#        Execute function in ``SingularDefaultContext``.
     462#        """
    447463        with SingularDefaultContext():
    448464            return func(*args, **kwds)
    449 
    450     from sage.misc.sageinspect import sage_getsource
    451     wrapper._sage_src_ = lambda: sage_getsource(func)
    452     wrapper.__name__ = func.__name__
    453     wrapper.__doc__ = func.__doc__
    454465    return wrapper
    455466
    456467def libsingular_standard_options(func):
    457     """
     468    r"""
    458469    Decorator to force a reduced Singular groebner basis.
    459470
    460471    TESTS::
     
    465476        sage: "buchberger" in sage_getsource(J.interreduced_basis)
    466477        True
    467478
     479    The following tests against a bug that was fixed in trac ticket #11298::
     480
     481        sage: from sage.misc.sageinspect import sage_getsourcelines, sage_getargspec
     482        sage: P.<x,y> = QQ[]
     483        sage: I = P*[x,y]
     484        sage: sage_getargspec(I.interreduced_basis)
     485        ArgSpec(args=['self'], varargs=None, keywords=None, defaults=None)
     486        sage: sage_getsourcelines(I.interreduced_basis)
     487        (['    @singular_standard_options\n',
     488          '    @libsingular_standard_options\n',
     489          '    def interreduced_basis(self):\n',
     490          ...
     491          '        return ret\n'], ...)
     492
    468493    .. note::
    469494
    470495       This decorator is used automatically internally so the user
    471496       does not need to use it manually.
    472497    """
     498    from sage.misc.decorators import sage_wraps
     499    @sage_wraps(func)
    473500    def wrapper(*args, **kwds):
    474501        """
    475502        Execute function in ``LibSingularDefaultContext``.
    476503        """
    477504        with LibSingularDefaultContext():
    478505            return func(*args, **kwds)
    479 
    480     from sage.misc.sageinspect import sage_getsource
    481     wrapper._sage_src_ = lambda: sage_getsource(func)
    482     wrapper.__name__ = func.__name__
    483     wrapper.__doc__ = func.__doc__
    484506    return wrapper
    485507
    486508class MagmaDefaultContext:
     
    531553    Decorator to force default options for Magma.
    532554
    533555    EXAMPLE::
     556
    534557        sage: P.<a,b,c,d,e> = PolynomialRing(GF(127))
    535558        sage: J = sage.rings.ideal.Cyclic(P).homogenize()
    536559        sage: from sage.misc.sageinspect import sage_getsource
     
    538561        True
    539562
    540563    """
     564    from sage.misc.decorators import sage_wraps
     565    @sage_wraps(func)
    541566    def wrapper(*args, **kwds):
    542567        """
    543568        Execute function in ``MagmaDefaultContext``.
    544569        """
    545570        with MagmaDefaultContext():
    546571            return func(*args, **kwds)
    547 
    548     from sage.misc.sageinspect import sage_getsource
    549     wrapper._sage_src_ = lambda: sage_getsource(func)
    550     wrapper.__name__ = func.__name__
    551     wrapper.__doc__ = func.__doc__
    552572    return wrapper
    553573
    554574class RequireField(MethodDecorator):
     
    901921            ...
    902922            ValueError: Coefficient ring must be a field for function 'complete_primary_decomposition'.
    903923       
    904         ALGORITHM: Uses Singular.
     924        ALGORITHM:
     925
     926        Uses Singular.
    905927
    906928        .. note::
    907929       
     
    977999            sage: reduce(lambda Qi,Qj: Qi.intersection(Qj), pd) == I
    9781000            True
    9791001       
    980         ALGORITHM: Uses Singular.
     1002        ALGORITHM:
     1003
     1004        Uses Singular.
    9811005       
    9821006        REFERENCES:
    9831007
     
    10411065            [Ideal (z^3 + 2, y - z^2) of Multivariate Polynomial Ring in x, y, z over Rational Field,
    10421066             Ideal (z^2 + 1, y + 1) of Multivariate Polynomial Ring in x, y, z over Rational Field]
    10431067       
    1044         ALGORITHM: Uses Singular.
     1068        ALGORITHM:
     1069
     1070        Uses Singular.
    10451071       
    10461072        REFERENCES:
    10471073
     
    12071233            verbose 0 (...: multi_polynomial_ideal.py, dimension) Warning: falling back to very slow toy implementation.
    12081234            2
    12091235
    1210         ALGORITHM: Uses Singular, unless the characteristic is too large.
     1236        ALGORITHM:
     1237
     1238        Uses Singular, unless the characteristic is too large.
    12111239
    12121240        .. note::
    12131241
     
    12761304        Return the vector space dimension of the ring modulo this ideal. If
    12771305        the ideal is not zero-dimensional, a TypeError is raised.
    12781306       
    1279         ALGORITHM: Uses Singular.
     1307        ALGORITHM:
     1308
     1309        Uses Singular.
    12801310       
    12811311        EXAMPLE::
    12821312       
     
    13501380             b*d^4 - b + d^5 - d, b*c - b*d + c^2*d^4 + c*d - 2*d^2,
    13511381             b^2 + 2*b*d + d^2, a + b + c + d]
    13521382       
    1353         ALGORITHM: Uses Singular.
     1383        ALGORITHM:
     1384
     1385        Uses Singular.
    13541386       
    13551387        .. note::
    13561388
     
    14961528            b*d^4 - b + d^5 - d, b*c - b*d + c^2*d^4 + c*d - 2*d^2,
    14971529            b^2 + 2*b*d + d^2, a + b + c + d]
    14981530       
    1499         ALGORITHM: Uses libSINGULAR.
     1531        ALGORITHM:
     1532
     1533        Uses libSINGULAR.
    15001534        """
    15011535        from sage.rings.polynomial.multi_polynomial_ideal_libsingular import std_libsingular, slimgb_libsingular
    15021536        from sage.libs.singular import singular_function
     
    16151649            of Multivariate Polynomial Ring in x, y, z over Rational
    16161650            Field]
    16171651       
    1618         ALGORITHM: Uses Singular.
     1652        ALGORITHM:
     1653
     1654        Uses Singular.
    16191655        """
    16201656        import sage.libs.singular
    16211657        minAssGTZ = sage.libs.singular.ff.primdec__lib.minAssGTZ
     
    17051741            sage: I.integral_closure()
    17061742            [x^2, y^5, -x*y^3]
    17071743       
    1708         ALGORITHM: Use libSingular
     1744        ALGORITHM:
     1745
     1746        Uses libSINGULAR.
    17091747        """
    17101748        from sage.rings.polynomial.multi_polynomial_sequence import PolynomialSequence
    17111749
     
    17351773            sage: M*G
    17361774            (0, 0)
    17371775       
    1738         ALGORITHM: Uses Singular's syz command
     1776        ALGORITHM:
     1777
     1778        Uses Singular's syz command.
    17391779        """
    17401780        import sage.libs.singular
    17411781        syz = sage.libs.singular.ff.syz
     
    18271867            sage: I.interreduced_basis()
    18281868            [x]
    18291869       
    1830         ALGORITHM: Uses Singular's interred command or
     1870        ALGORITHM:
     1871
     1872        Uses Singular's interred command or
    18311873        :func:`sage.rings.polynomial.toy_buchberger.inter_reduction``
    18321874        if conversion to Singular fails.
    18331875        """
     
    18721914       
    18731915            S * G = \sum_{i=0}^{m} h_ig_i ---->_G 0.
    18741916       
    1875         ALGORITHM: Uses Singular
     1917        ALGORITHM:
     1918
     1919        Uses Singular.
    18761920       
    18771921        EXAMPLE::
    18781922       
     
    20252069             y^9 - y^7*x^2 - y^7*x - y^6*x^3 - y^6*x^2 - 3*y^6 - 3*y^5*x - y^3*x^7 - 3*y^3*x^6
    20262070             - 3*y^3*x^5 - y^3*x^4 - 9*y^2*x^5 - 18*y^2*x^4 - 9*y^2*x^3 - 27*y*x^3 - 27*y*x^2 - 27*x]
    20272071
    2028         ALGORITHM: Uses Singular
     2072        ALGORITHM:
     2073
     2074        Uses Singular.
    20292075        """
    20302076        from sage.rings.polynomial.multi_polynomial_sequence import PolynomialSequence
    20312077        R = self.ring()
     
    20762122            Ideal (y^2 - x*z, x*y - z, x^2 - y) of Multivariate
    20772123            Polynomial Ring in x, y, t, s, z over Rational Field
    20782124       
    2079         ALGORITHM: Uses SINGULAR
     2125        ALGORITHM:
     2126
     2127        Uses Singular.
    20802128       
    20812129        .. note::
    20822130
     
    23392387            sage: I.variety()
    23402388            [...{y: -q^3, x: 0}...]
    23412389       
    2342         ALGORITHM: Uses triangular decomposition.
     2390        ALGORITHM:
     2391
     2392        Uses triangular decomposition.
    23432393        """
    23442394        def _variety(T, V, v=None):
    23452395            """
     
    24922542        in case it is finite dimensional and if the input is a standard
    24932543        basis with respect to the ring ordering.
    24942544       
    2495         INPUT: algorithm - defaults to use libsingular, if it is anything
    2496         else we will use the kbase() command
     2545        INPUT:
     2546
     2547        ``algorithm`` - defaults to use libsingular, if it is anything
     2548        else we will use the ``kbase()`` command
    24972549       
    24982550        EXAMPLES::
    24992551       
     
    25572609        Return the Groebner basis for this ideal, computed using
    25582610        Macaulay2.
    25592611       
    2560         ALGORITHM: Computed using Macaulay2. A big advantage of Macaulay2
    2561         is that it can compute the Groebner basis of ideals in polynomial rings
    2562         over the integers.
     2612        ALGORITHM:
     2613
     2614        Computed using Macaulay2. A big advantage of Macaulay2 is that
     2615        it can compute the Groebner basis of ideals in polynomial
     2616        rings over the integers.
    25632617       
    25642618        EXAMPLE::
    25652619       
     
    26422696        Return a set of generators / a basis of self. This is usually the
    26432697        set of generators provided during object creation.
    26442698     
    2645         EXAMPLE:
     2699        EXAMPLE::
    26462700     
    26472701           sage: P.<x,y> = PolynomialRing(QQ,2)
    26482702           sage: I = Ideal([x,y+1]); I
     
    30363090            Y^2 + (-3/5)*Z^2 + (2/5*t^2 - 2/5*t + 1/15)*Y + (-2/5*t^2 + 2/5*t - 1/15)*Z - 1/10*t^4 + 1/5*t^3 - 7/30*t^2 + 2/5*t + 11/90,
    30373091            Y*Z + 6/5*Z^2 + (1/5*t^2 - 1/5*t + 1/30)*Y + (4/5*t^2 - 4/5*t + 2/15)*Z + 1/5*t^4 - 2/5*t^3 + 7/15*t^2 - 3/10*t - 11/45, X + 2*Y + 2*Z + t^2 - t - 1/3]
    30383092
    3039         ALGORITHM: Uses Singular, Magma (if available), Macaulay2 (if
    3040         available), or a toy implementation.
     3093        ALGORITHM:
     3094
     3095        Uses Singular, Magma (if available), Macaulay2 (if available),
     3096        or a toy implementation.
    30413097        """
    30423098        from sage.rings.finite_rings.integer_mod_ring import is_IntegerModRing
    30433099        from sage.rings.polynomial.multi_polynomial_sequence import PolynomialSequence