Ways of optimizing

• _validate_mappings function
  Two lists keys = [] and values = [] are just used for accumulation and membership check, though inefficiently.
  Instead, the more optimized way is to rely on dict.values() view object converted to set for fast containment check.
  The optimized function would look as (docstrings are skipped for demo):

  def _validate_mappings(mappings: dict) -> None:
      values = set(mappings.values())
      for key, value in mappings.items():
          if key in values:
              raise _KeyValueConflictException(_KEY_VALUE_CONFLICT_EXCEPTION_MSG.format(key, value))
  

• mapping_replace function in use_regex=True mode and dealing with multiple regex replacements.
  To replace a loop of numerous subsequent regex compilations and substitutions I would suggest a "single-pass" substitution powered by the following features:

  • regex alternation group (...)|(...)|(...) to combine all raw patterns into one
  • Python dict preserves its insertion order since 3.7
  • the respective replacement string is found using Match.lastindex feature (the integer index of the last matched capturing group)

  Although, this trick may require non-overlapping patterns provided in mappings dict.
  The crucial if use_regex: block:

  ...
  if use_regex:
      keys_list = list(mappings.keys())
      replacer = lambda m: mappings[keys_list[m.lastindex - 1]]
      pat = fr"{'|'.join(f'({k})' for k in mappings.keys())}"   # composing regex alternation group
      replaced_string = re.sub(pat, replacer, replaced_string)
  

I've added some extended test case (3rd one) to show how's the regex trick goes:

print(mapping_replace("simple test", {"simple": "complex", "test": "haha"}))
print(mapping_replace("124233 test", {r"\d+": "letters"}, True))
print(mapping_replace("011 test ABCbb11www", {"\d+": "symbols", "[A-Z]+": "@", "w+": "W3W"}, True))
print(mapping_replace("Hello world", {"H": "J", "J": "Y"}, False, validate_mappings=False))  # No exception!
print(mapping_replace("Hello world", {"H": "J", "J": "Y"}))

The output:

complex haha
letters test
symbols test @bbsymbolsW3W
Yello world
raise _KeyValueConflictException(_KEY_VALUE_CONFLICT_EXCEPTION_MSG.format(key, value))
__main__._KeyValueConflictException: The key of 'J' -> 'Y' conflicts with a separate mapping containing the value 'J'.

    address = "123 north anywhere street"
    
    for word, initial in {"NORTH": "N", "SOUTH": "S"}.items():
        address = address.replace(word.lower(), initial)
    print(address)

nice and concise and readable too.

Mostly this looks good, but I’ll make a few suggestions:

Boolean arguments in your function signature

These control whether certain strings/mappings are lowercased first. I think this behaviour should be removed from keymap_replace(). It's scope creep: it’s gone from being string replacements to more complicated string manipulations. I’d leave that sort of manipulation to the caller.

(And you could continue to add options like this: what about uppercasing the string, or reversing it, or another pattern. Rather than muddling up your function with this, I’d just take it out.)

That makes the arguments simpler, and simplifies the function definition as well.

But if you really want those parameters in there, then I’d suggest making them keyword-only. In Python 3, you can insert an asterisk as so:

def keymap_replace(
    string: str, 
    mappings: dict,
    *,
    lower_keys=False,
    lower_values=False,
    lower_string=False,
) -> str:

and when the function is called, those boolean arguments have to be as keyword arguments, not positional. There can never be ambiguity in how the function is being used.

Dictionaries are unordered

There’s a possibility for ambiguity, or for substitutions to be chained. For example:

keymap_replace('Hello world', {
    'J': 'K',
    'H': 'J'
})

Should this call return "Jello world" or "Kello world"?

I think the first is more natural – I don’t expect substitutions to be chained – but when I tried the function, I got the latter. You should try to make this less confusing.

One possibility that springs to mind:

replaced_string = ''.join(mappings.get(char, char) for char in string)

Each character in the original string is subject to at most one substitution.

If keys in dictionary have only one word is possible split, map by get and join back:

a = ' '.join(d.get(x, x) for x in string.split())
print (a)
Sam and Ann are not good friends

If possible multiple words and also is necessary use words boundaries for avoid replace substrings:

import re

string = 'John and Mary are good friends'
d = {'John and': 'Sam with', 'Mary': 'Ann', 'are good': 'are not'}

pat = '|'.join(r"\b{}\b".format(x) for x in d.keys())
a = re.sub(pat, lambda x: d.get(x.group(0)), string)
print (a) 
Sam with Ann are not friends

via dict.update() function

In case you need a declarative solution, you can use dict.update() to change values in a dict.

Either like this:

my_dict.update({'key1': 'value1', 'key2': 'value2'})

or like this:

my_dict.update(key1='value1', key2='value2')

via dictionary unpacking

Since Python 3.5 you can also use dictionary unpacking for this:

my_dict = { **my_dict, 'key1': 'value1', 'key2': 'value2'}

Note: This creates a new dictionary.

via merge operator or update operator

Since Python 3.9 you can also use the merge operator on dictionaries:

my_dict = my_dict | {'key1': 'value1', 'key2': 'value2'}

Note: This creates a new dictionary.

Or you can use the update operator:

my_dict |= {'key1': 'value1', 'key2': 'value2'}