Ticket #3738: 3738-10-coerce_docs.patch

File 3738-10-coerce_docs.patch, 10.3 KB (added by robertwb, 11 years ago)
  • sage/rings/integer_mod.pyx

    # HG changeset patch
    # User Robert Bradshaw <robertwb@math.washington.edu>
    # Date 1217319884 25200
    # Node ID 97cdacff109aca5c54002ee9a3c98bdadde3b229
    # Parent  27e83edacc1d49910e524078502f855bc490d872
    Add some more documentation.
    
    diff -r 27e83edacc1d -r 97cdacff109a sage/rings/integer_mod.pyx
    a b cdef class IntegerMod_abstract(sage.stru 
    950950    def _latex_(self):
    951951        return str(self)
    952952
    953     def _integer_(self):
     953    def _integer_(self, ZZ=None):
    954954        return self.lift()
    955955
    956956    def _rational_(self):
  • sage/structure/coerce.pyx

    diff -r 27e83edacc1d -r 97cdacff109a sage/structure/coerce.pyx
    a b from parent import Set_PythonType 
    8484
    8585import sys, traceback
    8686
    87 from coerce_actions import LeftModuleAction, RightModuleAction, PyScalarAction, IntegerMulAction
     87from coerce_actions import LeftModuleAction, RightModuleAction, IntegerMulAction
    8888
    8989cpdef py_scalar_parent(py_type):
    9090    """
  • sage/structure/coerce_actions.pyx

    diff -r 27e83edacc1d -r 97cdacff109a sage/structure/coerce_actions.pyx
    a b cdef class ModuleAction(Action): 
    113113           
    114114
    115115    def _repr_name_(self):
     116        """
     117        The default name of this action type, which is has a sane default.
     118       
     119        EXAMPLES:
     120            sage: from sage.structure.coerce_actions import LeftModuleAction, RightModuleAction
     121            sage: A = LeftModuleAction(ZZ, ZZ['x']); A
     122            Left scalar multiplication by Integer Ring on Univariate Polynomial Ring in x over Integer Ring
     123            sage: A._repr_name_()
     124            'scalar multiplication'
     125            sage: RightModuleAction(GF(5), GF(5)[['t']])
     126            Right scalar multiplication by Finite Field of size 5 on Power Series Ring in t over Finite Field of size 5
     127        """
    116128        return "scalar multiplication"
    117129       
    118130    def codomain(self):
    cdef class RightModuleAction(ModuleActio 
    212224
    213225
    214226
    215 cdef class PyScalarAction(Action):
    216     r"""
    217     This class implements the action of a python scalar (e.g. an int or float)
    218     on a \sage element.
    219     """
    220     def __init__(self, Action action):
    221         Action.__init__(self, action.G, action.S, action._is_left, action.op)
    222         self._action = action
    223 
    224     cpdef Element _call_(self, a, b):
    225         if self._is_left:
    226             a = self.G(a)
    227             return self._action._call_(a,b)
    228         else:
    229             b = self.G(b)
    230             return self._action._call_(a,b)
    231    
    232     def __inverse__(self):
    233         return PyScalarAction(~self._action)
    234 
    235 
    236227cdef class IntegerMulAction(Action):
    237228
    238229    def __init__(self, ZZ, M, is_left=True):
    cdef class IntegerMulAction(Action): 
    248239            sage: act = IntegerMulAction(ZZ, R)
    249240            sage: act(5, x)
    250241            5*x
     242            sage: act(0, x)
     243            0
     244            sage: act(-3, x-1)
     245            -3*x + 3           
    251246        """
    252247        if PY_TYPE_CHECK(ZZ, type):
    253248            from sage.structure.parent import Set_PythonType
    cdef class IntegerMulAction(Action): 
    256251        Action.__init__(self, ZZ, M, is_left, operator.mul)
    257252
    258253    cpdef Element _call_(self, nn, a):
     254        """
     255        EXAMPLES:
     256            sage: from sage.structure.coerce_actions import IntegerMulAction
     257            sage: act = IntegerMulAction(ZZ, GF(101))
     258            sage: act(3, 9)
     259            27
     260            sage: act(3^689, 9)
     261            42
     262            sage: 3^689 * mod(9, 101)
     263            42
     264           
     265        Use round off error to verify this is doing actual repeated addition
     266        instead of just multiplying:
     267            sage: act = IntegerMulAction(ZZ, RR)
     268            sage: act(49, 1/49) == 49*RR(1/49)
     269            False
     270        """
    259271        if not self._is_left:
    260272            a, nn = nn, a
    261273        if not PyInt_CheckExact(nn):
    cdef class IntegerMulAction(Action): 
    265277               
    266278        return fast_mul_long(a, PyInt_AS_LONG(nn))
    267279       
    268     def __inverse__(self):
     280    def __invert__(self):
     281        """
     282        EXAMPLES:
     283            sage: from sage.structure.coerce_actions import IntegerMulAction
     284            sage: act = IntegerMulAction(ZZ, CDF)       
     285            sage: ~act
     286            Traceback (most recent call last):
     287            ...
     288            TypeError: No generic module division by Z.
     289        """
    269290        raise TypeError, "No generic module division by Z."
    270291       
    271     def _repr_type(self):
     292    def _repr_name_(self):
     293        """
     294        EXAMPLES:
     295            sage: from sage.structure.coerce_actions import IntegerMulAction
     296            sage: IntegerMulAction(ZZ, GF(5))
     297            Left Integer Multiplication by Integer Ring on Finite Field of size 5
     298        """
    272299        return "Integer Multiplication"
    273300
    274301
  • sage/structure/coerce_maps.pyx

    diff -r 27e83edacc1d -r 97cdacff109a sage/structure/coerce_maps.pyx
    a b cdef class NamedConvertMap(Map): 
    106106    """
    107107   
    108108    def __init__(self, domain, codomain, method_name, force_use=False):
     109        """
     110        EXAMPLES:
     111            sage: from sage.structure.coerce_maps import NamedConvertMap
     112            sage: mor = NamedConvertMap(SR, QQ['t'], '_polynomial_')
     113            sage: mor(x^2/4+1)
     114            1/4*t^2 + 1
     115            sage: mor = NamedConvertMap(SR, GF(7)[['t']], '_polynomial_')
     116            sage: mor(x^2/4+1)
     117            1 + 2*t^2
     118        """
    109119        if PY_TYPE_CHECK(domain, type):
    110120            domain = Set_PythonType(domain)
    111121        Map.__init__(self, domain, codomain)
    cdef class NamedConvertMap(Map): 
    114124        self.method_name = method_name
    115125   
    116126    cpdef Element _call_(self, x):
     127        """
     128        EXAMPLES:
     129            sage: from sage.structure.coerce_maps import NamedConvertMap
     130            sage: f = NamedConvertMap(GF(5), QQ, '_integer_'); f
     131            Conversion via _integer_ method map:
     132              From: Finite Field of size 5
     133              To:   Rational Field
     134            sage: f(19)
     135            4
     136            sage: f(19).parent()
     137            Rational Field
     138        """
    117139        try:
    118140            method = getattr(x, self.method_name)
    119141        except AttributeError:
    cdef class NamedConvertMap(Map): 
    134156        return e
    135157
    136158    def _repr_type(self):
    137         return "Conversion via %s" % self.method_name
     159        return "Conversion via %s method" % self.method_name
    138160   
    139161cdef class CallableConvertMap(Map):
    140162    cdef bint _parent_as_first_arg
  • sage/structure/parent.pyx

    diff -r 27e83edacc1d -r 97cdacff109a sage/structure/parent.pyx
    a b cdef class Parent(category_object.Catego 
    186186            '_initial_action_list': self._initial_action_list,
    187187            '_initial_convert_list': self._initial_convert_list,
    188188            '_element_init_pass_parent': self._element_init_pass_parent,
    189 
    190189        }
    191190           
    192191    def __getstate__(self):
    193         #print self._introspect_coerce()
    194192        d = CategoryObject.__getstate__(self)
    195193        d['_embedding'] = self._embedding
    196194        d['_element_constructor'] = self._element_constructor
    cdef class Parent(category_object.Catego 
    218216                                           init_no_parent=not d['_element_init_pass_parent'])
    219217
    220218    def __call__(self, x=0, *args, **kwds):
     219        """
     220        This is the generic call method for all parents.
     221       
     222        When called, it will find a map based on the Parent (or type) of x.
     223        If a coercion exists, this it will always be chosen. This map will
     224        then be called (with the arguments and keywords if any).
     225       
     226        By default this will dispatch as quickly as possible to
     227        \code{self._element_constructor_()} though faster pathways are
     228        possible if so desired.
     229        """
    221230        cdef Py_ssize_t i
    222231        R = parent_c(x)
    223232        cdef bint no_extra_args = PyTuple_GET_SIZE(args) == 0 and PyDict_Size(kwds) == 0
    cdef class Parent(category_object.Catego 
    236245                self._convert_from_hash.pop(mor.domain(), None)
    237246                for i from 0 <= i < len(self._convert_from_list):
    238247                    if self._convert_from_list[i] is mor:
    239                         self._convert_from_list = self._convert_from_list[:i] + self._convert_from_list[i+1:]
     248                        del self._convert_from_list[i]
    240249                        break
    241250                raise
    242251           
    cdef class Parent(category_object.Catego 
    321330        return the_list
    322331               
    323332    def __nonzero__(self):
     333        """
     334        By default, all Parents are treated as True when used in an if
     335        statement. Override this method if other behavior is desired
     336        (for example, for empty sets).
     337       
     338        EXAMPLES:
     339            sage: if ZZ: print "Yes"
     340            Yes
     341        """
    324342        return True
    325343
    326344    def __len__(self):
    cdef class Parent(category_object.Catego 
    715733        return None
    716734
    717735    cpdef convert_map_from(self, S):
     736        if self._convert_from_hash is None: # this is because parent.__init__() does not always get called
     737            self.init_coerce()
    718738        try:
    719739            return self._convert_from_hash[S]
    720740        except KeyError:
  • sage/structure/parent_old.pyx

    diff -r 27e83edacc1d -r 97cdacff109a sage/structure/parent_old.pyx
    a b cdef class Parent(parent.Parent): 
    8989        # old
    9090        self._has_coerce_map_from = {}
    9191       
    92     def init_coerce(self, dummy=True):
    93         if self._coerce_from_hash is None:
    94 #            print "init_coerce() for ", type(self)
    95             self._coerce_from_list = []
    96             self._coerce_from_hash = {}
    97             self._action_list = []
    98             self._action_hash = {}
     92    def init_coerce(self, dummy=False):
     93        parent.Parent.init_coerce(self, dummy)
    9994
    10095       
    10196    #################################################################################