Python format_map() Method

What You’ll Learn

The format_map() method fills {placeholder} fields in a string using values from a mapping—most often a dictionary. It is the mapping-based counterpart to format(): instead of passing keyword arguments, you pass one object that already holds your data. This is ideal for templates stored in variables or loaded from configuration files.

Definition and Usage

In Python, format_map() performs placeholder substitution. You write a template string with curly-brace names, such as "Hello, {name}!", and supply a mapping whose keys match those names. Python looks up each key and inserts the corresponding value into the result.

This method is closely related to format(). In fact, template.format_map(data) behaves like template.format(**data) when data is a plain dictionary—but format_map() accepts any mapping object, including custom classes that implement __getitem__ or __missing__.

📝 Syntax

The format_map() method takes one required argument:

string.format_map(mapping)

Syntax Rules

• string — the template containing {name} placeholders.
• mapping — a dict-like object whose keys match placeholder names.
• Return value — a new str with all placeholders filled in.
• Format specifiers — supported inside braces, e.g. {price:.2f} or {name:>10}.
• Missing keys — raise KeyError unless the mapping defines __missing__.
• Immutable — the original template string is never modified.

Examples Gallery

Run these examples in any Python 3 interpreter. Placeholder names inside {} must match keys in your mapping.

data = {"name": "John", "age": 25}
template = "Hello, my name is {name} and I am {age} years old."

result = template.format_map(data)

print("Template:", template)
print("Result:  ", result)

Template: Hello, my name is {name} and I am {age} years old.
Result:   Hello, my name is John and I am 25 years old.

class Person:
    def __init__(self, name, age):
        self.name = name
        self.age = age

person = Person(name="Alice", age=30)
template = "This is {name}. {name} is {age} years old."

result = template.format_map(vars(person))
print(result)

This is Alice. Alice is 30 years old.

report = "Product: {item:<12} Price: ${price:.2f}  Qty: {qty:03d}"

data = {"item": "Notebook", "price": 4.5, "qty": 7}
print(report.format_map(data))

Product: Notebook     Price: $4.50  Qty: 007

template = "User {user} logged in from {ip}"
data = {"user": "admin", "ip": "192.168.1.10"}

via_map = template.format_map(data)
via_format = template.format(**data)

print("format_map:", via_map)
print("format:    ", via_format)
print("Equal?     ", via_map == via_format)

format_map: User admin logged in from 192.168.1.10
format:     User admin logged in from 192.168.1.10
Equal?      True

class SafeDict(dict):
    def __missing__(self, key):
        return "{" + key + "}"

template = "Hello, {name}! Your role is {role}."
data = {"name": "Sam"}

result = template.format_map(SafeDict(data))
print(result)

Hello, Sam! Your role is {role}.

↩ Return Value

format_map() always returns a new string with placeholders replaced by values from the mapping. The original template string is not modified. If a required key is missing and the mapping has no __missing__ handler, Python raises KeyError instead of returning a partial result.

🚀 Common Use Cases

• Email and message templates — store a template string and fill it from user data.
• Config-driven output — load format strings from JSON or YAML and apply runtime values.
• Logging — build readable log lines from structured dict records.
• Report generation — combine row data with column templates in loops.
• Object serialization — format instance attributes via vars(obj) without manual concatenation.

📝 Notes

• Placeholder names must match mapping keys exactly—they are case-sensitive ({Name} ≠ {name}).
• Literal curly braces in output require doubling: "{{" and "}}".
• format_map() does not accept positional arguments; use format() for {0}, {1} style indexing.
• For simple two-value insertion, f-strings (f"Hello, {name}") are often more readable in modern Python.
• Extra keys in the mapping that are not used in the template are silently ignored.

💡 Best Practices