Аннотация LiteralString модуля typing в Python

Аннотация строковых литералов в Python

Аннотация typing.LiteralString - это специальный тип, который включает только литеральные строки (добавлено в Python 3.11.).

Строковый литерал, аннотированный LiteralString, совместим с другой LiteralString, НО объект, типизированный просто как str, НЕ СОВМЕСТИМ. Строка, созданная путем составления (конкатенации) объектов типа LiteralString, также допустима в качестве LiteralString.

Другими словами, аннотация typing.LiteralString полезна для конфиденциальных API, где произвольные строки, созданные пользователем, могут вызвать проблемы.

Аннотация LiteralString может использоваться для указания того, что параметр функции может относиться к любому литеральному строковому типу. Это позволяет функции принимать произвольные типы литеральных строк, а также строки, созданные из других литеральных строк. Затем средства проверки типов могут обеспечить, чтобы конфиденциальные функции, такие как те, которые выполняют операторы SQL или команды оболочки, вызывались только со статическими аргументами, обеспечивая защиту от атак путем внедрения.

Например, функция запроса SQL может быть аннотирована следующим образом:

def run_query(sql: LiteralString) -> ...
    ...

def caller(arbitrary_string: str, literal_string: LiteralString) -> None:
    run_query("SELECT * FROM students")  # проверка типа -> OK
    run_query(literal_string)  # проверка типа -> OK
    run_query("SELECT * FROM " + literal_string)  # проверка типа -> OK
    run_query(arbitrary_string)  # ошибка проверки типа
    run_query(  # ошибка проверки типа
        f"SELECT * FROM students WHERE name = {arbitrary_string}"
    )

Два приведенных выше случая, генерируют ошибки проверки типов или могут быть уязвимы для атаки путем внедрения SQL-кода.

Новое в Python 3.11.