Ticket #12518: trac_12518-enumerated_set_from_iterator-review-ts.patch

File trac_12518-enumerated_set_from_iterator-review-ts.patch, 10.9 KB (added by Travis Scrimshaw, 10 years ago)
  • sage/sets/set_from_iterator.py

    # HG changeset patch
    # User Travis Scrimshaw <tscrim@ucdavis.edu>
    # Date 1354256463 -3600
    # Node ID c8aeefcb5c40ba2e52f1829a3f6e7abf9f7e4e63
    # Parent  2488d0b6f4d80de8a7e255bcdd4082da939de32d
    Trac #12518: Review patch
    
    diff --git a/sage/sets/set_from_iterator.py b/sage/sets/set_from_iterator.py
    a b class EnumeratedSetFromIterator(Parent): 
    7878
    7979    INPUT:
    8080
    81     - ``f`` - a function that returns an iterable from which the set is built from.
     81    - ``f`` -- a function that returns an iterable from which the set is
     82      built from
    8283
    83     - ``args`` - tuple - the argument that are sent to the function ``f``.
     84    - ``name`` -- An optional name for the set
    8485
    85     - ``kwds`` - dictionnary - keywords that are sent to the function ``f``.
     86    - ``category`` -- (Default: ``None``) An optional category for that
     87      enumerated set. If you know that your iterator will stop after a finite
     88      number of steps you should set it as :class:`FiniteEnumeratedSets`,
     89      conversly if you know that your iterator will run over and over you
     90      should set it as :class:`InfiniteEnumeratedSets`.
    8691
    87     - ``name`` - string - an optional name for the set.
    88 
    89     - ``category`` - None or category (default: None) - a category for that
    90       enumerated set. If you know that your iterator will stop after a finite
    91       number of steps you should set it as FiniteEnumeratedSets(), conversly if
    92       you know that your iterator will run over and over you should set it as
    93       InfiniteEnumeratedSets().
    94 
    95     - ``cache`` - boolean (default: ``False``) - Whether or not use a cache
     92    - ``cache`` -- (default: ``False``) Boolean whether or not use a cache
    9693      mechanism for the iterator. If ``True``, then the function ``f`` is called
    9794      only once.
    9895
    class EnumeratedSetFromIterator(Parent): 
    123120
    124121    TESTS:
    125122
    126     The cache is compatible with multiple call to __iter__::
     123    The cache is compatible with multiple call to ``__iter__``::
    127124
    128125        sage: from itertools import count
    129126        sage: E = EnumeratedSetFromIterator(count, args=(0,), category=InfiniteEnumeratedSets(), cache=True)
    class EnumeratedSetFromIterator(Parent): 
    142139        sage: E = EnumeratedSetFromIterator(xsrange, args=(10,), category=FiniteEnumeratedSets(), cache=True)
    143140        sage: TestSuite(E).run()
    144141
    145     Remark that in order to make the TestSuite works, the elements of the set
    146     should have parents.
     142    ..NOTE::
     143
     144        In order to make the ``TestSuite`` works, the elements of the set
     145        should have parents.
    147146    """
    148147    def __init__(self, f, args=None, kwds=None, name=None, category=None, cache=False):
    149148        """
    class EnumeratedSetFromIterator(Parent): 
    204203
    205204    def _repr_(self):
    206205        r"""
     206        Return a string representation of ``self``.
     207
    207208        TESTS::
    208209
    209210            sage: from sage.sets.set_from_iterator import EnumeratedSetFromIterator
    class EnumeratedSetFromIterator(Parent): 
    253254        r"""
    254255        Equality test.
    255256
    256         The function returns ``True`` if and only if other is an enumerated set and
    257         has the same element as self.
     257        The function returns ``True`` if and only if other is an enumerated
     258        set and has the same element as ``self``.
    258259
    259260        TESTS::
    260261
    class EnumeratedSetFromIterator(Parent): 
    309310        r"""
    310311        Difference test.
    311312
    312         The function calls the __eq__ test.
     313        The function calls the ``__eq__`` test.
    313314
    314315        TESTS::
    315316
    class EnumeratedSetFromIterator(Parent): 
    332333
    333334    def __iter__(self):
    334335        r"""
    335         Returns an iterator over the element of self.
     336        Returns an iterator over the element of ``self``.
    336337
    337338        EXAMPLES::
    338339
    class EnumeratedSetFromIterator(Parent): 
    370371
    371372    def _element_constructor_(self, el):
    372373        """
     374        Construct an element from ``el``.
     375
    373376        TESTS::
    374377
    375378            sage: from sage.sets.set_from_iterator import EnumeratedSetFromIterator
    class Decorator: 
    504507
    505508class EnumeratedSetFromIterator_function_decorator(Decorator):
    506509    r"""
    507     Decorator for EnumeratedSetFromIterator.
     510    Decorator for :class:`EnumeratedSetFromIterator`.
    508511
    509     Name could be string or a function (args,kwds) -> string
     512    Name could be string or a function ``(args,kwds) -> string``.
     513
     514    .. WARNING::
     515
     516        If you are going to use this with the decorator ``cached_function``,
     517        you must place the ``cached_function`` first. See the example below.
    510518
    511519    EXAMPLES::
    512520
    class EnumeratedSetFromIterator_function 
    520528        sage: f(100)
    521529        {1, 3, 7, 13, 21, ...}
    522530
    523     To avoid ambiguity, it is always better to use it with a call which provides
    524     optional global initialization for the call to EnumeratedSetFromIterator::
     531    To avoid ambiguity, it is always better to use it with a call which
     532    provides optional global initialization for the call to
     533    :class:`EnumeratedSetFromIterator`::
    525534
    526535        sage: @set_from_function(category=InfiniteEnumeratedSets())
    527536        ... def Fibonacci():
    class EnumeratedSetFromIterator_function 
    552561        sage: f(n=100,m=1) == E
    553562        True
    554563
    555     An example which mixes together set_from_function and cached_method::
     564    An example which mixes together ``set_from_function`` and
     565    ``cached_method``::
    556566
    557567        sage: @cached_function
    558568        ... @set_from_function(
    class EnumeratedSetFromIterator_function 
    567577        sage: Graphs(10) is Graphs(10)
    568578        True
    569579
     580    The ``cached_function`` must go first::
     581
     582        sage: @set_from_function(
     583        ...    name = "Graphs on %(n)d vertices",
     584        ...    category = FiniteEnumeratedSets(),
     585        ...    cache = True)
     586        ... @cached_function
     587        ... def Graphs(n): return graphs(n)
     588        sage: Graphs(10)
     589        Graphs on 10 vertices
     590        sage: Graphs(10).unrank(0)
     591        Graph on 10 vertices
     592        sage: Graphs(10) is Graphs(10)
     593        False
    570594    """
    571595    def __init__(self, f=None, name=None, **options):
    572596        r"""
     597        Initialize ``self``.
     598
    573599        TESTS::
    574600
    575601            sage: from sage.sets.set_from_iterator import set_from_function
    class EnumeratedSetFromIterator_function 
    592618
    593619    def __call__(self, *args, **kwds):
    594620        r"""
    595         Build a new EnumeratedSet by calling self.f with apropriate argument. If
    596         f is None, then returns a new instance of EnumeratedSetFromIterator
     621        Build a new :class:`EnumeratedSet` by calling ``self.f`` with
     622        apropriate argument. If ``f`` is ``None``, then returns a new instance
     623        of :class:`EnumeratedSetFromIterator`.
    597624
    598625        EXAMPLES::
    599626
    class EnumeratedSetFromIterator_method_c 
    641668
    642669    INPUT:
    643670
    644     - ``inst`` - an instance of a class
     671    - ``inst`` -- an instance of a class
    645672
    646     - ``f`` - a method of a class of ``inst`` (and not of the instance itself)
     673    - ``f`` -- a method of a class of ``inst`` (and not of the instance itself)
    647674
    648     - ``name`` - optional - either a string (which may contains substitution
    649       rules from argument or a function args,kwds -> string.
     675    - ``name`` -- Optional string (which may contains substitution
     676      rules from argument or a function ``(args,kwds) -> string``.
    650677
    651     - ``options`` - options to be sent to EnumeratedSetFromIterator
     678    - any option accepted by :class:`EnumeratedSetFromIterator`
    652679    """
    653680    def __init__(self, inst, f, name=None, **options):
    654681        r"""
     682        Initialize ``self``.
     683
    655684        TESTS:
    656685
    657686        We test if pickling works correctly on the Permutation class (in
    658         sage.combinat.permutation) because its method bruhat_succ and
    659         bruhat_pred are decorated with set_from_method::
     687        :mod:`sage.combinat.permutation`) because its method ``bruhat_succ``
     688        and ``bruhat_pred`` are decorated with ``set_from_method``::
    660689
    661690            sage: from sage.combinat.permutation import Permutation_class
    662691            sage: loads(dumps(Permutation_class))
    class EnumeratedSetFromIterator_method_c 
    680709
    681710    def __call__(self,*args,**kwds):
    682711        r"""
    683         Returns an instance of EnumeratedSetFromIterator with proper argument.
     712        Returns an instance of :class:`EnumeratedSetFromIterator` with
     713        proper argument.
    684714
    685715        TESTS::
    686716
    class EnumeratedSetFromIterator_method_d 
    713743
    714744    INPUT:
    715745
    716     - ``f`` - function (optional) - the function from which are built the
    717       enumerated sets at each call
     746    - ``f`` -- Optional function from which are built the enumerated sets at
     747      each call
    718748
    719     - ``name`` - optional - either a string (which may contains substitution
    720       rules from argument or a function args,kwds -> string.
     749    - ``name`` -- Optional string (which may contains substitution
     750      rules from argument or a function ``(args,kwds) -> string``
    721751
    722     - any option accepted by EnumeratedSetFromIterator.
     752    - any option accepted by :class:`EnumeratedSetFromIterator`
    723753
    724754    EXAMPLES::
    725755
    class EnumeratedSetFromIterator_method_d 
    770800        sage: F.list()
    771801        [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
    772802
    773     TODO: It is not yet possible to use set_from_method in conjunction with
    774     cached_method.
     803    .. TODO::
     804
     805        It is not yet possible to use ``set_from_method`` in conjunction with
     806        ``cached_method``.
    775807    """
    776808    def __init__(self, f=None, **options):
    777809        r"""
     810        Initialize ``self``.
     811
    778812        TESTS:
    779813
    780814        We test if pickling works correctly on the Permutation class (in
    781         sage.combinat.permutation) because its method bruhat_succ and
    782         bruhat_pred are decorated with set_from_method::
     815        :mod:`sage.combinat.permutation`) because its method ``bruhat_succ``
     816        and ``bruhat_pred`` are decorated with ``set_from_method``::
    783817
    784818            sage: from sage.combinat.permutation import Permutation_class
    785819            sage: loads(dumps(Permutation_class))
    class EnumeratedSetFromIterator_method_d 
    810844
    811845    def __call__(self, f):
    812846        r"""
    813         Trick if EnumeratedSetFromIterator_method was created with some options
    814         and is called with a function as argument.
     847        Trick if :class:`EnumeratedSetFromIterator_method` was created with
     848        some options and is called with a function as argument.
    815849
    816         TEST::
     850        TESTS::
    817851
    818852            sage: from sage.sets.set_from_iterator import set_from_method
    819853            sage: class A:
    class EnumeratedSetFromIterator_method_d 
    838872            sage: a = A()
    839873            sage: print a.f.__class__
    840874            sage.sets.set_from_iterator.EnumeratedSetFromIterator_method_caller
    841 
    842         You would hardly ever see an instance of this class alive.
    843875        """
     876        # You would hardly ever see an instance of this class alive.
    844877        return EnumeratedSetFromIterator_method_caller(inst, self.f, **self.options)
    845878
    846879set_from_method = EnumeratedSetFromIterator_method_decorator