StringGenerator 0.5.0__tar.gz → 0.5.1__tar.gz

{stringgenerator-0.5.0 → stringgenerator-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: StringGenerator
-Version: 0.5.0
+Version: 0.5.1
 Summary: Generate randomized strings of characters using a template
 Home-page: https://github.com/paul-wolf/strgen
 Author: Paul Wolf

{stringgenerator-0.5.0 → stringgenerator-0.5.1}/StringGenerator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: StringGenerator
-Version: 0.5.0
+Version: 0.5.1
 Summary: Generate randomized strings of characters using a template
 Home-page: https://github.com/paul-wolf/strgen
 Author: Paul Wolf

{stringgenerator-0.5.0 → stringgenerator-0.5.1}/strgen/__init__.py

@@ -42,7 +42,7 @@ from abc import ABC, abstractmethod
 from collections import Counter, namedtuple
 from math import factorial
 
-__version__ = "0.5.0"
+__version__ = "0.5.1"
 __author__ = "Paul Wolf"
 __license__ = "BSD"
 
@@ -306,9 +306,29 @@ class StringGenerator:
             return "".join(char_list)
 
         def count(self, randomizer, **kwargs):
-            """This does not work for complex expressions."""
-            char_list = list("".join([x.render(randomizer, **kwargs) for x in self.seq]))
-            return permutation_count(char_list)
+            """Number of distinct outcomes of a permutation ('&') of the operands.
+
+            '&' shuffles together the characters produced by all operands. When
+            every operand is fixed -- it has exactly one possible value, i.e.
+            ``count() == 1`` -- the multiset of characters is known, and the
+            answer is just the number of distinct permutations of that multiset.
+
+            When an operand can vary (e.g. a character set), the set of
+            characters being shuffled changes with each random draw, so there is
+            no single well-defined count. Rather than return a misleading,
+            draw-dependent number (the previous behaviour) we raise
+            NotImplementedError. See ``StringGenerator.count`` for the full set
+            of assumptions behind counting.
+            """
+            operand_counts = [node.count(randomizer, **kwargs) for node in self.seq]
+            if all(c == 1 for c in operand_counts):
+                # every operand is fixed, so the multiset of characters is known
+                chars = "".join(node.render(randomizer, **kwargs) for node in self.seq)
+                return permutation_count(chars)
+            raise NotImplementedError(
+                "count() is undefined for '&' over operands that are not fixed; "
+                "the result would depend on the random draw"
+            )
 
         def dump(self, level=-1):
             print((StringGenerator.mytab * level) + repr(self))
@@ -706,6 +726,30 @@ class StringGenerator:
         return self.seq.render(self.randomizer, **kwargs)
 
     def count(self, **kwargs) -> int:
+        r"""Return the size of the generation sample space for the template.
+
+        This is the number of distinct strings the template can produce, but
+        only under the following assumptions. Where they do not hold, the value
+        is the size of the *generation* space (the number of ways the template
+        can be filled in), which may exceed the number of distinct strings:
+
+        * **Character classes contain no duplicate characters.** ``len(chars)``
+          is used as the alphabet size, so a class with repeats (e.g.
+          ``[a\d\d]``) counts each repeat as a separate option and overcounts.
+          The generator also weights repeated characters more heavily when
+          rendering, so this number reflects that weighting.
+        * **Alternation (``|``) branches are disjoint.** The count sums the
+          branch sizes, which equals the number of distinct results only if no
+          two branches can produce the same string; overlapping branches
+          overcount.
+        * **Permutation (``&``) is applied only to fixed operands.** For ``&``
+          over operands that can vary, the count depends on the random draw, so
+          ``count()`` raises NotImplementedError instead of guessing.
+
+        ``count()`` also raises NotImplementedError if the template contains a
+        ``${...}`` source, since a source may be an arbitrary callable or list
+        whose size is unknown.
+        """
         return self.seq.count(self.randomizer, **kwargs)
 
     def dump(self, cnt=None, **kwargs):

{stringgenerator-0.5.0 → stringgenerator-0.5.1}/strgen/tests.py

@@ -411,6 +411,22 @@ class TestSG(unittest.TestCase):
             SG(r"[\u\d]{2}|[abc]{3}", uaf=100).render_list(1323, unique=True)
         )
 
+    def test_count_and_operator(self):
+        """count() over '&' is deterministic and only defined for fixed operands."""
+        # Fixed (literal) operands: distinct permutations of "1abc" = 4! = 24.
+        sg = SG(r"1&abc")
+        assert sg.count() == 24
+        assert sg.count() == len(sg.render_set(24))
+
+        # Deterministic across repeated calls. Previously this rendered once and
+        # counted that single sample, so the value varied with the random draw.
+        assert len({SG(r"1&abc").count() for _ in range(20)}) == 1
+
+        # Operands that can vary have no single well-defined count: raise rather
+        # than return a draw-dependent number.
+        with self.assertRaises(NotImplementedError):
+            SG(r"[\d]{2}&[\d]{1}").count()
+
     def test_probabilistic_or(self):
         d = SG("0|1|2|3|4|5|6|7|8|9").render_list(10000)
         d = [int(d) for d in d]