For RegexGenerator, update the enforce_uniqueness parameter to cardinality_rule (#957)

Author: R-Palazzo

Diff for: rdt/transformers/id.py

@@ -7,7 +7,10 @@
 import pandas as pd
 
 from rdt.transformers.base import BaseTransformer
-from rdt.transformers.utils import strings_from_regex
+from rdt.transformers.utils import (
+    _handle_enforce_uniqueness_and_cardinality_rule,
+    strings_from_regex,
+)
 
 LOGGER = logging.getLogger(__name__)
 
@@ -82,9 +85,13 @@ class RegexGenerator(BaseTransformer):
         regex (str):
             String representing the regex function.
         enforce_uniqueness (bool):
-            Whether or not to ensure that the new generated data is all unique. If it isn't
-            possible to create the requested number of rows, then an error will be raised.
-            Defaults to ``False``.
+            **DEPRECATED** Whether or not to ensure that the new generated data is all unique.
+            If it isn't possible to create the requested number of rows, then an error will
+            be raised. Defaults to ``None``.
+        cardinality_rule (str):
+            Rule that the generated data must follow. If set to ``unique``, the generated
+            data must be unique. If set to ``None``, then the generated data may contain
+            duplicates. Defaults to ``None``.
         generation_order (str):
             String defining how to generate the output. If set to ``alphanumeric``, it will
             generate the output in alphanumeric order (ie. 'aaa', 'aab' or '1', '2'...). If
@@ -122,13 +129,16 @@ def __setstate__(self, state):
     def __init__(
         self,
         regex_format='[A-Za-z]{5}',
-        enforce_uniqueness=False,
+        cardinality_rule=None,
         generation_order='alphanumeric',
+        enforce_uniqueness=None,
     ):
         super().__init__()
         self.output_properties = {None: {'next_transformer': None}}
-        self.enforce_uniqueness = enforce_uniqueness
         self.regex_format = regex_format
+        self.cardinality_rule = _handle_enforce_uniqueness_and_cardinality_rule(
+            enforce_uniqueness, cardinality_rule
+        )
         self.data_length = None
         self.generator = None
         self.generator_size = None
@@ -158,16 +168,18 @@ def _transform(self, _data):
         """Drop the input column by returning ``None``."""
         return None
 
-    def _warn_not_enough_unique_values(self, sample_size):
+    def _warn_not_enough_unique_values(self, sample_size, unique_condition):
         """Warn the user that the regex cannot generate enough unique values.
 
         Args:
             sample_size (int):
                 Number of samples to be generated.
+            unique_condition (bool):
+                Whether or not to enforce uniqueness.
         """
         warned = False
         if sample_size > self.generator_size:
-            if self.enforce_uniqueness:
+            if unique_condition:
                 warnings.warn(
                     f"The regex for '{self.get_input_column()}' can only generate "
                     f'{self.generator_size} unique values. Additional values may not exactly '
@@ -185,7 +197,7 @@ def _warn_not_enough_unique_values(self, sample_size):
                 )
 
         remaining = self.generator_size - self.generated
-        if sample_size > remaining and self.enforce_uniqueness and not warned:
+        if sample_size > remaining and unique_condition and not warned:
             warnings.warn(
                 f'The regex generator is not able to generate {sample_size} new unique '
                 f'values (only {max(remaining, 0)} unique values left).'
@@ -201,12 +213,17 @@ def _reverse_transform(self, data):
         Returns:
             pandas.Series
         """
+        if hasattr(self, 'cardinality_rule'):
+            unique_condition = self.cardinality_rule == 'unique'
+        else:
+            unique_condition = self.enforce_uniqueness
+
         if data is not None and len(data):
             sample_size = len(data)
         else:
             sample_size = self.data_length
 
-        self._warn_not_enough_unique_values(sample_size)
+        self._warn_not_enough_unique_values(sample_size, unique_condition)
 
         remaining = self.generator_size - self.generated
         if sample_size > remaining:
@@ -225,7 +242,7 @@ def _reverse_transform(self, data):
         reverse_transformed = generated_values[:]
 
         if len(reverse_transformed) < sample_size:
-            if self.enforce_uniqueness:
+            if unique_condition:
                 try:
                     remaining_samples = sample_size - len(reverse_transformed)
                     start = int(generated_values[-1]) + 1

Diff for: rdt/transformers/pii/anonymizer.py

@@ -15,6 +15,7 @@
 from rdt.errors import TransformerInputError, TransformerProcessingError
 from rdt.transformers.base import BaseTransformer
 from rdt.transformers.categorical import LabelEncoder
+from rdt.transformers.utils import _handle_enforce_uniqueness_and_cardinality_rule
 
 
 class AnonymizedFaker(BaseTransformer):
@@ -113,22 +114,17 @@ def __init__(
         function_kwargs=None,
         locales=None,
         cardinality_rule=None,
-        enforce_uniqueness=False,
+        enforce_uniqueness=None,
         missing_value_generation='random',
     ):
         super().__init__()
         self._data_cardinality = None
         self.data_length = None
         self.enforce_uniqueness = enforce_uniqueness
         self.cardinality_rule = cardinality_rule.lower() if cardinality_rule else None
-        if enforce_uniqueness:
-            warnings.warn(
-                "The 'enforce_uniqueness' parameter is no longer supported. "
-                "Please use the 'cardinality_rule' parameter instead.",
-                FutureWarning,
-            )
-            if not self.cardinality_rule:
-                self.cardinality_rule = 'unique'
+        self.cardinality_rule = _handle_enforce_uniqueness_and_cardinality_rule(
+            enforce_uniqueness, cardinality_rule
+        )
 
         self.provider_name = provider_name if provider_name else 'BaseProvider'
         if self.provider_name != 'BaseProvider' and function_name is None:

Diff for: rdt/transformers/utils.py

@@ -367,3 +367,17 @@ def __getitem__(self, sdtype):
         phased out.
         """
         return self.get(sdtype)
+
+
+def _handle_enforce_uniqueness_and_cardinality_rule(enforce_uniqueness, cardinality_rule):
+    result = cardinality_rule
+    if enforce_uniqueness is not None:
+        warnings.warn(
+            "The 'enforce_uniqueness' parameter is no longer supported. "
+            "Please use the 'cardinality_rule' parameter instead.",
+            FutureWarning,
+        )
+        if enforce_uniqueness and cardinality_rule is None:
+            result = 'unique'
+
+    return result

Diff for: tests/integration/transformers/test_id.py

@@ -173,7 +173,7 @@ def test_input_data_bigger_than_data_length(self):
     def test_called_multiple_times(self):
         """Test the ``RegexGenerator`` with short regex and called multiple times.
 
-        This test ensures that when ``enforce_uniqueness`` is ``False`` this generator will
+        This test ensures that when ``cardinality_rule`` is ``None`` this generator will
         continue to work.
         """
         # Setup
@@ -223,11 +223,11 @@ def test_called_multiple_times(self):
         })
         pd.testing.assert_frame_equal(third_reverse_transform, expected_reverse_transformed)
 
-    def test_called_multiple_times_enforce_uniqueness(self):
-        """Test that calling multiple times with ``enforce_uniqueness`` returns unique values."""
+    def test_called_multiple_times_cardinality_rule_unique(self):
+        """Test calling multiple times when ``cardinality_rule`` is ``unique``."""
         # Setup
         data = pd.DataFrame({'my_column': np.arange(10)})
-        generator = RegexGenerator(enforce_uniqueness=True)
+        generator = RegexGenerator(cardinality_rule='unique')
 
         # Run
         transformed_data = generator.fit_transform(data, 'my_column')
@@ -303,13 +303,13 @@ def test_with_many_possibilities(self):
         pd.testing.assert_frame_equal(transformed, expected_transformed)
         pd.testing.assert_frame_equal(reverse_transform, expected_reverse_transformed)
 
-    def test_enforce_uniqueness_not_enough_values_categorical(self):
-        """Test with enforce_uniqueness=True but insufficient regex values."""
+    def test_cardinality_rule_unique_not_enough_values_categorical(self):
+        """Test with cardinality_rule='unique' but insufficient regex values."""
         # Setup
         data = pd.DataFrame({
             'id': [1, 2, 3, 4, 5],
         })
-        instance = RegexGenerator('id_[a-b]{1}', enforce_uniqueness=True)
+        instance = RegexGenerator('id_[a-b]{1}', cardinality_rule='unique')
 
         # Run
         transformed = instance.fit_transform(data, 'id')
@@ -319,13 +319,13 @@ def test_enforce_uniqueness_not_enough_values_categorical(self):
         expected = pd.DataFrame({'id': ['id_a', 'id_b', 'id_a(0)', 'id_b(0)', 'id_a(1)']})
         pd.testing.assert_frame_equal(reverse_transform, expected)
 
-    def test_enforce_uniqueness_not_enough_values_numerical(self):
-        """Test with enforce_uniqueness=True but insufficient regex values."""
+    def test_cardinality_rule_not_enough_values_numerical(self):
+        """Test with cardinality_rule='unique' but insufficient regex values."""
         # Setup
         data = pd.DataFrame({
             'id': [1, 2, 3, 4, 5],
         })
-        instance = RegexGenerator('[2-3]{1}', enforce_uniqueness=True)
+        instance = RegexGenerator('[2-3]{1}', cardinality_rule='unique')
 
         # Run
         transformed = instance.fit_transform(data, 'id')

Diff for: tests/unit/transformers/pii/test_anonymizer.py

@@ -126,7 +126,7 @@ def test___init___enforce_uniqueness_exists(self):
         instance = AnonymizedFaker()
 
         # Assert
-        assert instance.enforce_uniqueness is False
+        assert instance.enforce_uniqueness is None
 
     def test__function_cardinality_rule_unique(self):
         """Test that ``_function`` uses the ``faker.unique``.
@@ -367,8 +367,8 @@ def test___init__error_missing_value_generation(self):
 
     @patch('rdt.transformers.pii.anonymizer.faker')
     @patch('rdt.transformers.pii.anonymizer.AnonymizedFaker.check_provider_function')
-    @patch('rdt.transformers.pii.anonymizer.warnings')
-    def test___init__custom(self, mock_warnings, mock_check_provider_function, mock_faker):
+    @patch('rdt.transformers.pii.anonymizer._handle_enforce_uniqueness_and_cardinality_rule')
+    def test___init__custom(self, mock__handle, mock_check_provider_function, mock_faker):
         """Test the instantiation of the transformer with custom parameters.
 
         Test that the transformer can be instantiated with a custom provider and function, and
@@ -390,6 +390,9 @@ def test___init__custom(self, mock_warnings, mock_check_provider_function, mock_
               ``credit_card_full``.
             - the ``instance._function`` is ``instance.faker.credit_card_full``.
         """
+        # Setup
+        mock__handle.return_value = 'unique'
+
         # Run
         instance = AnonymizedFaker(
             provider_name='credit_card',
@@ -407,13 +410,7 @@ def test___init__custom(self, mock_warnings, mock_check_provider_function, mock_
         assert instance.locales == ['en_US', 'fr_FR']
         mock_faker.Faker.assert_called_once_with(['en_US', 'fr_FR'])
         assert instance.cardinality_rule == 'unique'
-        mock_warnings.warn.assert_has_calls([
-            call(
-                "The 'enforce_uniqueness' parameter is no longer supported. "
-                "Please use the 'cardinality_rule' parameter instead.",
-                FutureWarning,
-            )
-        ])
+        mock__handle.assert_called_once_with(True, None)
 
     def test___init__no_function_name(self):
         """Test the instantiation of the transformer with custom parameters.