Ticket #14248: trac_14248-global_options_case-review--am.patch

File trac_14248-global_options_case-review--am.patch, 8.4 KB (added by Andrew Mathas, 9 years ago)

Review patch which fixes some doc-strings and makes case_sensitive a boolean

  • sage/structure/global_options.py

    # HG changeset patch
    # User "sage-combinat script"
    # Date 1367290320 -36000
    # Node ID 83c59867b4701a3b93490eed9e147e6e699ef675
    # Parent  c623c38f2952526c745a956ac82e69011482ac5e
    Fixing doc-strngs and fine-tuning case sensitivity
    
    diff --git a/sage/structure/global_options.py b/sage/structure/global_options.py
    a b dictionary are: 
    6262- ``values`` -- A dictionary assigning each valid value for the option
    6363  to a short description of what it does.
    6464
    65 - ``case_sensitive`` -- (Default: ``True``) Set to ``False`` to make the
    66   check non-case sensitiv.e
     65- ``case_sensitive`` -- (Default: ``True``) ``True`` or ``False`` depending on
     66  whether the values of the option are case sensitive.
    6767
    68 For each option, one must supply either a complete list of values via ``values``
    69 or a validation function via ``checker``. The values can be quite arbitrary,
    70 including user-defined functions which customize the default behaviour of the
    71 classes such as the output of ``_repr_`` or :func:`latex`. See
    72 :ref:`dispatcher` below, and :meth:`~GlobalOptions.dispatcher`,
    73 for more information.
     68For each option, either a complete list of possible values, via ``values``, or a
     69validation function, via ``checker``, must be given. The values can be quite
     70arbitrary, including user-defined functions which customize the default
     71behaviour of the classes such as the output of ``_repr_`` or :func:`latex`. See
     72:ref:`dispatcher` below, and :meth:`~GlobalOptions.dispatcher`, for more
     73information.
    7474
    7575The documentation for the options is automatically constructed by combining the
    7676description of each option with a header and footer which are given by the
    Continuing the example from :ref:`constr 
    128128    sage: menu['dessert']
    129129    'espresso'
    130130
    131 Note that, provided there is no ambiguity. all options and their values can be
     131Note that, provided there is no ambiguity, options and their values can be
    132132abbreviated::
    133133
    134134    sage: menu['d']
    abbreviated:: 
    152152Setter functions
    153153----------------
    154154
    155 Each option of a :class:`GlobalOptions` can be equipped with an optiona setter
    156 function which is called **after** each change of value. In the following
    157 example, setting the option 'add' changes the state of the class by setting an
    158 attribute in this class using a :func:`classmethod`. Note that the options
    159 object is inserted after the creation of the class in order to access the
    160 :func:`classmethod` as ``A.setter``::
     155Each option of a :class:`GlobalOptions` can be equipped with an optional setter
     156function which is called **after** the value of the option is changed. In the
     157following example, setting the option 'add' changes the state of the class by
     158setting an attribute in this class using a :func:`classmethod`. Note that the
     159options object is inserted after the creation of the class in order to access
     160the :func:`classmethod` as ``A.setter``::
    161161
    162162    sage: from sage.structure.global_options import GlobalOptions
    163163    sage: class A(SageObject):
    Documentation for options 
    191191
    192192The documentation for a :class:`GlobalOptions` is automatically generated from
    193193the supplied options. For example, the generated documentation for the options
    194 ``menu`` defined in :ref:`construction_section`::
     194``menu`` defined in :ref:`construction_section` is the following::
    195195
    196196    Fancy documentation
    197197    -------------------
    Dispatchers 
    246246-----------
    247247
    248248The whole idea of a :class:`GlobalOptions` class is that the options change the
    249 default behaviour of associated classes. This can be done either by simply
     249default behaviour of the associated classes. This can be done either by simply
    250250checking what the current value of the relevant option is. Another possibility
    251251is to use the options class as a dispatcher to associated methods. To use the
    252252dispatcher feature of a :class:`GlobalOptions` class it is necessary to implement
    these methods is that they start with a  
    255255of the option.
    256256
    257257If the value of a dispatchable option is set equal to a (user defined) function
    258 then this function is called in instead of a class method.
     258then this function is called instead of a class method.
    259259
    260260For example, the options ``MyOptions`` can be used to dispatch the ``_repr_``
    261261method of the associated class ``MyClass`` as follows:
    In this example, ``first_option`` is an  
    275275values ``bells``, ``whistles``, and so on. Note that it is necessary to make
    276276``self``, which is an instance of ``MyClass``, an argument of the dispatcher
    277277because :meth:`~GlobalOptions.dispatch()` is a method of :class:`GlobalOptions`
    278 and not a method of ``MyClass``. Apart form ``MyOptions``, as it is a method of
     278and not a method of ``MyClass``. Apart from ``MyOptions``, as it is a method of
    279279this class, the arguments are the attached class (here ``MyClass``), the prefix
    280280of the method of ``MyClass`` being dispatched, the option of ``MyOptions``
    281281which controls the dispatching. All other arguments are passed through to the
    See :meth:`~GlobalOptions.dispatch` for  
    318318Doc testing
    319319-----------
    320320
    321 All of the options and their effects should be doctested. However, in order
     321All of the options and their effects should be doc-tested. However, in order
    322322not to break other tests, all options should be returned to their default state
    323323at the end of each test. To make this easier, every :class:`GlobalOptions` class has
    324324a :meth:`~GlobalOptions.reset()` method for doing exactly this.
    class GlobalOptions(SageObject): 
    409409      automatically defines the corresponding ``checker``). This dictionary
    410410      gives the possible options, as keys, together with a brief description
    411411      of them.
    412     - ``case_sensitive`` -- (Default: ``True``) Set to ``False`` to make the
    413       check non-case sensitiv.
     412    - ``case_sensitive`` -- (Default: ``True``) ``True`` or ``False`` depending on
     413      whether the values of the option are case sensitive.
    414414
    415415    Options and their values can be abbreviated provided that this
    416416    abbreviation is a prefix of a unique option.
    class GlobalOptions(SageObject): 
    774774        doc={}  # will be used to build the doc string
    775775        option = option.lower()
    776776        self._values[option] = []
     777        self._case_sensitive[option]=False    # ``False`` by by default
    777778        for spec in sorted(specifications):   # NB: options processed alphabetically!
    778779            if spec=='alias':
    779780                self._alias[option]=specifications[spec]
    class GlobalOptions(SageObject): 
    814815                for val in specifications[spec]:
    815816                    doc[val] = specifications[spec][val]
    816817                doc.update(specifications[spec])
    817                 if self._case_sensitive.get(option, True):
     818                if self._case_sensitive[option]:
    818819                    self._values[option] += [val for val in specifications[spec].keys()]
    819820                    self._display_values[option] = {val:val for val in specifications[spec].keys()}
    820821                else:
    class GlobalOptions(SageObject): 
    933934        orig_value = value
    934935
    935936        # convert to proper case if it is a string
    936         if isinstance(value, str) and not self._case_sensitive.get(option, True):
     937        if isinstance(value, str) and not self._case_sensitive[option]:
    937938            value = value.lower()
    938939
    939940        if option in self._values:
    class GlobalOptions(SageObject): 
    10671068        if option is None:
    10681069            for option in self._default_value:
    10691070                self._value[option] = self._default_value[option]
    1070                 if not self._case_sensitive.get(option, True):
     1071                if not self._case_sensitive[option] and isinstance(self._value[option],str):
    10711072                    self._value[option] = self._value[option].lower()
    10721073            for option in self._linked_value:
    10731074                link, linked_opt=self._linked_value[option]
    class GlobalOptions(SageObject): 
    10761077            option=self._match_option(option)
    10771078            if option in self._default_value:
    10781079                self._value[option] = self._default_value[option]
    1079                 if not self._case_sensitive.get(option, True):
     1080                if not self._case_sensitive[option] and isinstance(self._value[option],str):
    10801081                    self._value[option] = self._value[option].lower()
    10811082            elif option in self._linked_value:
    10821083                link, linked_opt=self._linked_value[option]