Python 3.11 introduced LiteralString as a way to enhance type safety when dealing with string literals, particularly in security-sensitive contexts like SQL queries, shell commands, and file paths. This guide explains what it is, why it matters, and how to use it effectively.
What is LiteralString?
LiteralString is a type hint that indicates a function should only accept string literals (hardcoded strings), not dynamically constructed strings. This helps prevent injection attacks by ensuring untrusted input can’t sneak into sensitive operations.
Basic Example
from typing import LiteralString
def run_query(sql: LiteralString) -> None:
# This function only accepts string literals like "SELECT * FROM users"
# Not f-strings or concatenated strings
print(f"Executing: {sql}")
run_query("SELECT * FROM users") # OK
run_query(f"SELECT * FROM {table}") # Type checker error!
Why Use LiteralString?
1. Security Against Injection Attacks
Many security vulnerabilities happen when dynamic strings are used in:
- SQL queries (
SQL injection) - Shell commands (
command injection) - File paths (
path traversal)
LiteralString forces developers to use trusted, hardcoded strings in critical operations.
2. Better Code Clarity
Makes it obvious which functions require compile-time constant strings.
3. Early Bug Detection
Type checkers (like mypy or pyright) will flag unsafe string usage before runtime.
How to Use LiteralString
Basic Usage
from typing import LiteralString
def execute_sql(query: LiteralString) -> None:
...
execute_sql("SELECT 1") # ✅ Allowed
execute_sql(input()) # ❌ Type error: Not a literal string
Combining with str for Flexibility
If a function can accept both literals and dynamic strings, use Union:
from typing import LiteralString, Union
def log_message(msg: Union[LiteralString, str]) -> None:
print(msg)
log_message("Hello") # ✅ Literal
log_message(get_dynamic_msg()) # ✅ Also allowed
Enforcing Safe String Building
If you must build strings dynamically, use a helper:
def build_safe_query(table: str) -> LiteralString:
# Only allow known-safe operations
return f"SELECT * FROM {table}" # ❌ Still not a LiteralString!
# (This is a limitation—see workarounds below)
(Note: LiteralString doesn’t automatically make f-strings safe. You still need validation.)
Limitations & Workarounds
1. LiteralString Doesn’t Validate Content
It only checks if the string is a literal, not whether it’s safe. You still need:
- Parameterized queries (for SQL)
shlex.quote()(for shell commands)pathlib.Path(for file paths)
2. No Direct Support for F-Strings
table = "users"
query = f"SELECT * FROM {table}" # Not a LiteralString!
Workaround: Use Final constants where possible:
from typing import Final, LiteralString
TABLE: Final = "users"
query: LiteralString = f"SELECT * FROM {TABLE}" # Works in some type checkers
3. Type Checker Support Required
- Requires
mypyorpyright(not enforced at runtime) - Not all type checkers fully support it yet
When Should You Use LiteralString?
| Use Case | Recommended? | Why? |
|---|---|---|
| Raw SQL queries | ✅ Yes | Prevents SQL injection |
| Shell commands | ✅ Yes | Blocks command injection |
| File paths | ✅ Yes | Avoids path traversal |
| General logging | ❌ No | Overkill for non-sensitive strings |
| User-provided data | ❌ No | LiteralString only works for literals |
Key Takeaways
LiteralStringhelps prevent injection attacks by restricting functions to string literals.- It works with type checkers (not at runtime).
- Doesn’t replace input validation—combine with other security practices.
- Best for SQL, shell commands, and file operations.
Example in a Real-World Scenario:
from typing import LiteralString
import sqlite3
def get_user(db: sqlite3.Connection, user_id: int) -> None:
# UNSAFE:
query = f"SELECT * FROM users WHERE id = {user_id}" # ❌ SQL injection risk!
db.execute(query)
# SAFE (with LiteralString + parameterization):
safe_query: LiteralString = "SELECT * FROM users WHERE id = ?"
db.execute(safe_query, (user_id,)) # ✅ Secure
By adopting LiteralString, you make your code safer by design—a hallmark of truly professional Python development.
