collisions
collisions
¶
Collision rules for structured replacements.
Every replacement follows the same rules:
- It differs from its own original, ignoring letter case and surrounding whitespace. This rule is strict.
- In an identifier-like column whose original values are all distinct, such as a key column, replacements stay distinct too, ignoring case. When retries cannot find an unused value, an earlier replacement is repeated and counted so the caller can warn. A new replacement there also avoids the values of columns that share replacements with it, so a value shared into it later is not a repeat. Other columns may repeat replacements, and a replacement may equal another row's original.
- A full-name replacement avoids keeping the original's first or last name; when retries cannot, it keeps one and is counted.
A grouping column is stricter: its replacements must be one-to-one, so two groups never merge, and no repeat fallback is allowed.
Classes:
| Name | Description |
|---|---|
ReplacementOwners |
The original each replacement went to, for one identifier column or one shared format. |
CandidateChooser |
Choose one replacement from successive generated candidates under the collision rules. |
Functions:
| Name | Description |
|---|---|
all_distinct |
Return whether there is at least one value and no two are equal, ignoring letter case. |
Attributes:
| Name | Type | Description |
|---|---|---|
IDENTIFIER_ENTITY_TYPES |
Entity types whose columns never give two different originals the same replacement. |
|
ReplacementOutcome |
How a replacement was chosen: a new value, or one of the fallbacks in preference order. |
IDENTIFIER_ENTITY_TYPES = frozenset({EntityType.EMAIL, EntityType.PHONE_NUMBER, EntityType.NATIONAL_ID, EntityType.CREDIT_DEBIT_CARD, EntityType.API_KEY, EntityType.IPV4, EntityType.IPV6, EntityType.UNIQUE_IDENTIFIER})
module-attribute
¶
Entity types whose columns never give two different originals the same replacement.
ReplacementOutcome = Literal['new', 'repeat', 'kept_name_part', 'kept_birth_date']
module-attribute
¶
How a replacement was chosen: a new value, or one of the fallbacks in preference order.
ReplacementOwners()
¶
The original each replacement went to, for one identifier column or one shared format.
A replacement may repeat for the same original, as when it appears in several records, but two different originals must not share one. Values are compared ignoring letter case.
Example
After record("X-1", "a-7"), "x-1" is taken for original "B-2" but not for "A-7".
Methods:
| Name | Description |
|---|---|
record |
Note that |
taken_for |
Return the case-folded replacements that |
Source code in src/nemo_safe_synthesizer/pii_replacer/replacement/collisions.py
CandidateChooser(entity_type, original, pattern=None, *, used=None, one_to_one=None, written_suffix='', locale='en_US')
¶
Choose one replacement from successive generated candidates under the collision rules.
Offer candidates until one is accepted as new or the caller runs out of attempts, then take the best fallback. The chooser does not record the chosen value; the caller does.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
entity_type
|
EntityType
|
Entity type of the value being replaced. |
required |
original
|
str
|
Original text the replacement must differ from. |
required |
pattern
|
str | None
|
Plan pattern of the target, used to read full names and skip their fixed words. |
None
|
used
|
Container[str] | None
|
Case-folded values this original should not get because other originals have them, in its
column and in the columns that share replacements with it. |
None
|
one_to_one
|
Container[str] | None
|
The same values for a grouping column. When given, a candidate in this set is rejected outright and no repeat fallback is allowed, so two groups never share one. |
None
|
written_suffix
|
str
|
Text written after every candidate, such as the original locality kept after a generated street. The one-to-one check applies to the candidate followed by this text, since that is the value two groups must not share. |
''
|
locale
|
str
|
Locale whose name order full names are read in. |
'en_US'
|
Methods:
| Name | Description |
|---|---|
offer |
Return whether |
fallback |
Return the best rejected candidate and how it falls short, or |
Source code in src/nemo_safe_synthesizer/pii_replacer/replacement/collisions.py
offer(request, candidate)
¶
Return whether candidate can be used as a new replacement; otherwise keep it as a fallback.
Source code in src/nemo_safe_synthesizer/pii_replacer/replacement/collisions.py
fallback()
¶
Return the best rejected candidate and how it falls short, or None if none is usable.
Repeating an earlier replacement is preferred over keeping an original name part, and both over keeping an original birth date. A one-to-one target only accepts a kept name part.
Source code in src/nemo_safe_synthesizer/pii_replacer/replacement/collisions.py
all_distinct(values)
¶
Return whether there is at least one value and no two are equal, ignoring letter case.
Example
["A-1", "a-2"] is all distinct; ["A-1", "a-1"] and [] are not.