-

cool-RR · cool-RR · commit ecc8177bc9f2 · 2014-09-24T16:33:15.000+03:00
diff --git a/source_py3/python_toolbox/misc_tools/misc_tools.py b/source_py3/python_toolbox/misc_tools/misc_tools.py
@@ -345,6 +345,18 @@ def decimal_number_from_string(string):
 
 
 class AlternativeLengthMixin:
+    '''
+    Mixin for sized types that makes it easy to return non-standard lengths.
+    
+    Due to CPython limitation, Python's built-in `__len__` (and its counterpart
+    `len`) can't return really big values or floating point numbers.
+    
+    Classes which need to return such lengths can use this mixin. They'll have
+    to define a property `length` where they return their length, and if
+    someone tries to call `len` on it, then if the length happens to be a
+    number that `len` supports, it'll return that, otherwise it'll show a
+    helpful error message.
+    '''
     def __len__(self):
         length = self.length
         if (length <= sys.maxsize) and isinstance(length, int):
diff --git a/source_py3/python_toolbox/sequence_tools/misc.py b/source_py3/python_toolbox/sequence_tools/misc.py
@@ -278,21 +278,24 @@ def ensure_iterable_is_sequence(iterable, default_type=tuple,
 class CanonicalSlice:
     def __init__(self, slice_, iterable_or_length=None, offset=0):
         '''
-        blocktododoc iterable_or_length, also note result, if not given iterable/length, can't really be used as slice (only as canonical object) because of `infinity`
+        Parse a `slice` object into a `CanonicalSlice` with start, stop, step.
         
-        Parse a `slice` object into a canonical `(start, stop, step)`.
-    
         This is helpful because `slice`'s own `.start`, `.stop` and `.step` are
         sometimes specified as `None` for convenience, so Python will infer
-        them automatically. Here we make them explicit.
-    
-        if `start` is `None`, it will be set to `0` (if the `step` is positive)
-        or `infinity` (if the `step` is negative.)
+        them automatically. Here we make them explicit. If we're given an
+        iterable (or the length of one) in `iterable_or_length`, we'll give a
+        canoncial slice for that length, otherwise we'll do a generic one,
+        which is rarely usable for actual slicing because it often has
+        `infinity` in it, so it's useful only for canonalization. (e.g.
+        checking whether two different slices are actually equal.)
     
-        if `stop` is `None`, it will be set to `infinity` (if the `step` is
+        When doing a generic canonical slice (without giving an iterable or
+        length):
+            If `start` is `None`, it will be set to `0` (if the `step` is
+        positive) or `infinity` (if the `step` is negative.)
+            If `stop` is `None`, it will be set to `infinity` (if the `step` is
         positive) or `0` (if the `step` is negative.)
-    
-        If `step` is `None`, it will be changed to the default `1`.
+            If `step` is `None`, it will be changed to the default `1`.
         '''
         from . import math_tools
         
@@ -401,6 +404,7 @@ def __init__(self, slice_, iterable_or_length=None, offset=0):
     
 class CuteSequenceMixin(misc_tools.AlternativeLengthMixin):
     def take_random(self):
+        '''Take a random item from the sequence.'''
         return self[random.randint(0, get_length(self) - 1)]
     def __contains__(self, item):
         try: self.index(item)
