Zusammenfassung

Es gibt derzeit keine Möglichkeit, mittels Typannotationen anzugeben, dass ein Funktionsparameter vom Typ eines beliebigen literalen Strings sein kann. Wir müssen einen präzisen literalen String-Typ angeben, wie z. B. Literal["foo"]. Dieses PEP führt einen Obertyp für literale String-Typen ein: LiteralString. Dies ermöglicht es einer Funktion, beliebige literale String-Typen zu akzeptieren, wie z. B. Literal["foo"] oder Literal["bar"].

Motivation

Leistungsstarke APIs, die SQL oder Shell-Befehle ausführen, empfehlen oft, dass sie mit literalen Strings aufgerufen werden, anstatt mit beliebigen benutzergesteuerten Strings. Es gibt jedoch keine Möglichkeit, diese Empfehlung im Typsystem auszudrücken, was manchmal zu Sicherheitslücken führt, wenn Entwickler sie nicht befolgen. Zum Beispiel ist eine naive Methode, einen Benutzereintrag aus einer Datenbank abzurufen, die Annahme einer Benutzer-ID und deren Einfügung in eine vordefinierte SQL-Abfrage

def query_user(conn: Connection, user_id: str) -> User:
    query = f"SELECT * FROM data WHERE user_id = {user_id}"
    conn.execute(query)
    ...  # Transform data to a User object and return it

query_user(conn, "user123")  # OK.

Die benutzergesteuerten Daten user_id werden jedoch mit dem SQL-Befehlsstring vermischt, was bedeutet, dass ein böswilliger Benutzer beliebige SQL-Befehle ausführen könnte

 # Delete the table.
 query_user(conn, "user123; DROP TABLE data;")

 # Fetch all users (since 1 = 1 is always true).
 query_user(conn, "user123 OR 1 = 1")

Um solche SQL-Injection-Angriffe zu verhindern, bieten SQL-APIs parametrisierte Abfragen an, die die ausgeführte Abfrage von benutzergesteuerten Daten trennen und die Ausführung beliebiger Abfragen unmöglich machen. Zum Beispiel wäre mit sqlite3 unsere ursprüngliche Funktion sicher als Abfrage mit Parametern geschrieben

def query_user(conn: Connection, user_id: str) -> User:
    query = "SELECT * FROM data WHERE user_id = ?"
    conn.execute(query, (user_id,))
    ...

Das Problem ist, dass es keine Möglichkeit gibt, diese Disziplin zu erzwingen. Die Dokumentation von sqlite3 selbst kann den Leser nur ermahnen, das sql-Argument nicht dynamisch aus externen Eingaben zu erstellen; die API-Autoren können dies nicht durch das Typsystem ausdrücken. Benutzer können immer noch eine praktische f-Zeichenkette wie zuvor verwenden (und tun dies oft) und ihren Code anfällig für SQL-Injektion lassen.

Bestehende Werkzeuge, wie der beliebte Sicherheitslinter Bandit, versuchen, unsichere externe Daten in SQL-APIs zu erkennen, indem sie die AST oder andere semantische Mustervergleiche inspizieren. Diese Werkzeuge schließen jedoch gängige Idiome aus, wie z. B. das Speichern einer großen mehrzeiligen Abfrage in einer Variablen, bevor sie ausgeführt wird, das Hinzufügen von literalen String-Modifikatoren zur Abfrage basierend auf einigen Bedingungen oder die Transformation des Abfrage-Strings mithilfe einer Funktion. (Wir untersuchen existierende Werkzeuge im Abschnitt Abgelehnte Alternativen.) Viele Werkzeuge erkennen beispielsweise ein falsch positives Problem in diesem harmlosen Ausschnitt

def query_data(conn: Connection, user_id: str, limit: bool) -> None:
    query = """
        SELECT
            user.name,
            user.age
        FROM data
        WHERE user_id = ?
    """
    if limit:
        query += " LIMIT 1"

    conn.execute(query, (user_id,))

Wir möchten die schädliche Ausführung von benutzergesteuerten Daten verbieten und gleichzeitig harmlose Idiome wie das obige zulassen, ohne zusätzliche Benutzerarbeit zu verlangen.

Um dieses Ziel zu erreichen, führen wir den Typ LiteralString ein, der nur String-Werte akzeptiert, von denen bekannt ist, dass sie aus Literalen bestehen. Dies ist eine Verallgemeinerung des Typs Literal["foo"] aus PEP 586. Ein String vom Typ LiteralString kann keine benutzergesteuerten Daten enthalten. Daher ist jede API, die nur LiteralString akzeptiert, immun gegen Injektionslücken (mit pragmatischen Einschränkungen).

Da wir möchten, dass die execute-Methode von sqlite3 Strings, die mit Benutzereingaben erstellt wurden, nicht zulässt, würden wir ihren Typeshed-Stub so ändern, dass er eine sql-Abfrage vom Typ LiteralString akzeptiert

from typing import LiteralString

def execute(self, sql: LiteralString, parameters: Iterable[str] = ...) -> Cursor: ...

Dies verbietet erfolgreich unser unsicheres SQL-Beispiel. Die Variable query wird unten als Typ str inferiert, da sie aus einer Formatzeichenkette unter Verwendung von user_id erstellt wurde, und kann nicht an execute übergeben werden

def query_user(conn: Connection, user_id: str) -> User:
    query = f"SELECT * FROM data WHERE user_id = {user_id}"
    conn.execute(query)  # Error: Expected LiteralString, got str.
    ...

Die Methode bleibt flexibel genug, um unser komplizierteres Beispiel zuzulassen

def query_data(conn: Connection, user_id: str, limit: bool) -> None:
    # This is a literal string.
    query = """
        SELECT
            user.name,
            user.age
        FROM data
        WHERE user_id = ?
    """

    if limit:
        # Still has type LiteralString because we added a literal string.
        query += " LIMIT 1"

    conn.execute(query, (user_id,))  # OK

Beachten Sie, dass der Benutzer seinen SQL-Code überhaupt nicht ändern musste. Der Typ-Checker konnte den literalen String-Typ inferieren und nur bei Verstößen beanstanden.

LiteralString ist auch in anderen Fällen nützlich, in denen wir eine strenge Trennung von Befehlen und Daten wünschen, z. B. beim Erstellen von Shell-Befehlen oder beim Rendern eines Strings in eine HTML-Antwort ohne Escaping (siehe Anhang A: Andere Verwendungen). Insgesamt erleichtert diese Kombination aus Striktheit und Flexibilität die Erzwingung einer sichereren API-Nutzung in sensiblem Code, ohne die Benutzer zu belasten.

Begründung

Erstens, warum Typen verwenden, um Sicherheitslücken zu verhindern?

Benutzer in der Dokumentation zu warnen, ist nicht ausreichend - die meisten Benutzer sehen diese Warnungen entweder nie oder ignorieren sie. Die Verwendung eines bestehenden dynamischen oder statischen Analyseansatzes ist zu restriktiv - diese verhindern natürliche Idiome, wie wir im Abschnitt Motivation gesehen haben (und ausführlicher im Abschnitt Abgelehnte Alternativen diskutieren werden). Der typisierungsbasierte Ansatz in diesem PEP bietet eine benutzerfreundliche Balance zwischen Striktheit und Flexibilität.

Laufzeitansätze funktionieren nicht, weil die Abfragezeichenkette zur Laufzeit eine normale str ist. Obwohl wir einige Exploits mit Heuristiken verhindern könnten, wie z. B. Regex-Filterung auf offensichtlich böswillige Payloads, wird es immer einen Weg geben, sie zu umgehen (die perfekte Unterscheidung zwischen guten und schlechten Abfragen reduziert sich auf das Halteproblem).

Statische Ansätze, wie die Überprüfung der AST, um zu sehen, ob die Abfragezeichenkette ein literales String-Ausdruck ist, können nicht feststellen, wann ein String einer Zwischenvariable zugewiesen wird oder wann er durch eine harmlose Funktion transformiert wird. Dies macht sie übermäßig restriktiv.

Der Typ-Checker schneidet überraschenderweise besser ab als beide, da er Zugriff auf Informationen hat, die in den Laufzeit- oder statischen Analyseansätzen nicht verfügbar sind. Insbesondere kann uns der Typ-Checker sagen, ob ein Ausdruck einen literalen String-Typ hat, z. B. Literal["foo"]. Der Typ-Checker propagiert bereits Typen über Variablendeklarationen oder Funktionsaufrufe.

Im aktuellen Typsystem selbst, wenn die Funktion für die Ausführung von SQL- oder Shell-Befehlen nur drei mögliche Eingabe-Strings akzeptieren würde, wäre unsere Aufgabe erledigt. Wir würden einfach sagen

def execute(query: Literal["foo", "bar", "baz"]) -> None: ...

Aber natürlich kann execute *jede* beliebige Abfrage akzeptieren. Wie stellen wir sicher, dass die Abfrage keinen beliebigen, benutzergesteuerten String enthält?

Wir möchten angeben, dass der Wert von einem Typ Literal[<...>] sein muss, wobei <...> ein String ist. Dies repräsentiert LiteralString. LiteralString ist der „Obertyp“ aller literalen String-Typen. Tatsächlich führt dieses PEP lediglich einen Typ in der Typenhierarchie zwischen Literal["foo"] und str ein. Jeder spezifische literale String, wie Literal["foo"] oder Literal["bar"], ist mit LiteralString kompatibel, aber nicht umgekehrt. Der „Obertyp“ von LiteralString selbst ist str. Daher ist LiteralString mit str kompatibel, aber nicht umgekehrt.

Beachten Sie, dass eine Union von literalen Typen natürlich mit LiteralString kompatibel ist, da jedes Element der Union einzeln mit LiteralString kompatibel ist. Daher ist Literal["foo", "bar"] mit LiteralString kompatibel.

Wir wollen jedoch nicht nur exakte literale Abfragen darstellen. Wir wollen auch die Komposition zweier literaler Strings unterstützen, wie z. B. query + " LIMIT 1". Dies ist mit dem obigen Konzept ebenfalls möglich. Wenn x und y zwei Werte vom Typ LiteralString sind, dann ist x + y ebenfalls von einem Typ, der mit LiteralString kompatibel ist. Wir können dies durch Betrachtung spezifischer Instanzen wie Literal["foo"] und Literal["bar"] nachvollziehen; der Wert des addierten Strings x + y kann nur "foobar" sein, was den Typ Literal["foobar"] hat und somit mit LiteralString kompatibel ist. Die gleiche Überlegung gilt, wenn x und y Unions von literalen Typen sind; das Ergebnis der paarweisen Addition zweier literaler Typen aus x bzw. y ist ein literaler Typ, was bedeutet, dass das Gesamtergebnis eine Union von literalen Typen ist und somit mit LiteralString kompatibel ist.

Auf diese Weise können wir Pythons Konzept eines Literal-String-Typs nutzen, um anzugeben, dass unsere API nur Strings akzeptieren kann, von denen bekannt ist, dass sie aus Literalen konstruiert sind. Spezifischere Details folgen in den restlichen Abschnitten.

Spezifikation

variable_annotation: LiteralString

def my_function(literal_string: LiteralString) -> LiteralString: ...

class Foo:
    my_attribute: LiteralString

type_argument: List[LiteralString]

T = TypeVar("T", bound=LiteralString)

bad_union: Literal["hello", LiteralString]  # Not OK
bad_nesting: Literal[LiteralString]  # Not OK

def foo(s: str) -> None:
    if s == "bar":
        reveal_type(s)  # => Literal["bar"]

literal_string: LiteralString
s: str = literal_string  # OK

literal_string: LiteralString = s  # Error: Expected LiteralString, got str.
literal_string: LiteralString = "hello"  # OK

def expect_literal_string(s: LiteralString) -> None: ...

expect_literal_string("foo" + "bar")  # OK
expect_literal_string(literal_string + "bar")  # OK

literal_string2: LiteralString
expect_literal_string(literal_string + literal_string2)  # OK

plain_string: str
expect_literal_string(literal_string + plain_string)  # Not OK.

expect_literal_string(",".join(["foo", "bar"]))  # OK
expect_literal_string(literal_string.join(["foo", "bar"]))  # OK
expect_literal_string(literal_string.join([literal_string, literal_string2]))  # OK

xs: List[LiteralString]
expect_literal_string(literal_string.join(xs)) # OK
expect_literal_string(plain_string.join([literal_string, literal_string2]))
# Not OK because the separator has type 'str'.

literal_string += "foo"  # OK
literal_string += literal_string2  # OK
literal_string += plain_string # Not OK

literal_name: LiteralString
expect_literal_string(f"hello {literal_name}")
# OK because it is composed from literal strings.

expect_literal_string("hello {}".format(literal_name))  # OK

expect_literal_string(f"hello")  # OK

username: str
expect_literal_string(f"hello {username}")
# NOT OK. The format-string is constructed from 'username',
# which has type 'str'.

expect_literal_string("hello {}".format(username))  # Not OK

some_int: int
expect_literal_string(some_int)  # Error: Expected LiteralString, got int.

literal_one: Literal[1] = 1
expect_literal_string(literal_one)  # Error: Expected LiteralString, got Literal[1].

def add_limit(query: LiteralString) -> LiteralString:
    return query + " LIMIT = 1"

def my_query(query: LiteralString, user_id: str) -> None:
    sql_connection().execute(add_limit(query), (user_id,))  # OK

def return_literal_string() -> LiteralString:
    return "foo" if condition1() else "bar"  # OK

def return_literal_str2(literal_string: LiteralString) -> LiteralString:
    return "foo" if condition1() else literal_string  # OK

def return_literal_str3() -> LiteralString:
    if condition1():
        result: Literal["foo"] = "foo"
    else:
        result: LiteralString = "bar"

    return result  # OK

from typing import Literal, LiteralString, TypeVar

TLiteral = TypeVar("TLiteral", bound=LiteralString)

def literal_identity(s: TLiteral) -> TLiteral:
    return s

hello: Literal["hello"] = "hello"
y = literal_identity(hello)
reveal_type(y)  # => Literal["hello"]

s: LiteralString
y2 = literal_identity(s)
reveal_type(y2)  # => LiteralString

s_error: str
literal_identity(s_error)
# Error: Expected TLiteral (bound to LiteralString), got str.

class Container(Generic[T]):
    def __init__(self, value: T) -> None:
        self.value = value

literal_string: LiteralString = "hello"
x: Container[LiteralString] = Container(literal_string)  # OK

s: str
x_error: Container[LiteralString] = Container(s)  # Not OK

xs: List[LiteralString] = ["foo", "bar", "baz"]

@overload
def foo(x: Literal["foo"]) -> int: ...
@overload
def foo(x: LiteralString) -> bool: ...
@overload
def foo(x: str) -> str: ...

x1: int = foo("foo")  # First overload.
x2: bool = foo("bar")  # Second overload.
s: str
x3: str = foo(s)  # Third overload.

Abwärtskompatibilität

Wir schlagen vor, typing_extensions.LiteralString für die Verwendung in früheren Python-Versionen hinzuzufügen.

Wie in PEP 586 erwähnt, können Typ-Checker „frei experimentieren, um ausgefeiltere Inferenztechniken zu verwenden“. Wenn der Typ-Checker also einen literalen String-Typ für eine nicht annotierte Variable inferiert, die mit einem literalen String initialisiert wird, sollte das folgende Beispiel in Ordnung sein

x = "hello"
expect_literal_string(x)
# OK, because x is inferred to have type 'Literal["hello"]'.

Dies ermöglicht eine präzise Typüberprüfung von idiomatischem SQL-Abfragecode, ohne den Code überhaupt annotieren zu müssen (wie im Beispiel im Abschnitt Motivation zu sehen ist).

Dieses PEP schreibt die obige Inferenzstrategie jedoch nicht vor, ebenso wie PEP 586. Falls der Typ-Checker x nicht als Typ Literal["hello"] inferiert, können Benutzer den Typ-Checker unterstützen, indem sie ihn explizit als x: LiteralString annotieren

x: LiteralString = "hello"
expect_literal_string(x)

Abgelehnte Alternativen

def build_insert_query(
    table: LiteralString
    insert_columns: Iterable[LiteralString],
) -> LiteralString:
    sql = "INSERT INTO " + table

    column_clause = ", ".join(insert_columns)
    value_clause = ", ".join(["?"] * len(insert_columns))

    sql += f" ({column_clause}) VALUES ({value_clause})"
    return sql

def insert_data(
    conn: Connection,
    kvs_to_insert: Dict[LiteralString, str]
) -> None:
    query = build_insert_query("data", kvs_to_insert.keys())
    conn.execute(query, kvs_to_insert.values())

# Example usage
data_to_insert = {
    "column_1": value_1,  # Note: values are not literals
    "column_2": value_2,
    "column_3": value_3,
}
insert_data(conn, data_to_insert)

SafeSQL = NewType("SafeSQL", str)

def execute(self, sql: SafeSQL, parameters: Iterable[str] = ...) -> Cursor: ...

execute(SafeSQL("SELECT * FROM data WHERE user_id = ?"), user_id)  # OK

user_query: str
execute(user_query)  # Error: Expected SafeSQL, got str.

query = f"SELECT * FROM data WHERE user_id = f{user_id}"
execute(SafeSQL(query))  # No error!

Referenzimplementierung

Dies ist in Pyre v0.9.8 implementiert und wird aktiv genutzt.

Die Implementierung erweitert den Typüberprüfer einfach um LiteralString als Obertyp von literalen String-Typen.

Um die Komposition durch Addition, Join usw. zu unterstützen, war es ausreichend, die Stubs für str in Pyres Kopie von typeshed zu überladen.

Anhang A: Andere Verwendungen

Um die Diskussion zu vereinfachen und minimale Sicherheitskenntnisse vorauszusetzen, haben wir uns im gesamten PEP auf SQL-Injections konzentriert. LiteralString kann jedoch auch verwendet werden, um viele andere Arten von Injection-Schwachstellen zu verhindern.

subprocess.run(f"echo 'Hello {name}'", shell=True)

echo 'Hello ' && rm -rf / #'

def run(command: LiteralString, *args: str, shell: bool=...): ...

 dangerous_string = django.utils.safestring.mark_safe(f"<script>{user_input}</script>")
 return(dangerous_string)

 def mark_safe(s: LiteralString) -> str: ...

template_str = "There are {{ len(values) }} values: {{ values }}"
template = jinja2.Template(template_str)
template.render(values=[1, 2])
# Result: "There are 2 values: [1, 2]"

 malicious_str = "{{''.__class__.__base__.__subclasses__()[408]('rm - rf /',shell=True)}}"
 template = jinja2.Template(malicious_str)
 template.render()
 # Result: The shell command 'rm - rf /' is run

 class Template:
     def __init__(self, source: LiteralString): ...

 external_string = "%(foo)999999999s"
 ...
 # Tries to add > 1GB of whitespace to the logged string:
 logger.info(f'Received: {external_string}', some_dict)

 def info(msg: LiteralString, *args: object) -> None:
     ...

Anhang B: Einschränkungen

Es gibt eine Reihe von Möglichkeiten, wie LiteralString Benutzer daran hindern könnte, Strings, die aus Nicht-Literal-Daten erstellt wurden, an eine API zu übergeben.

1. Wenn der Entwickler keinen Typüberprüfer verwendet oder keine Typannotationen hinzufügt, werden Verstöße nicht erkannt.

2. cast(LiteralString, non_literal_string) könnte verwendet werden, um dem Typüberprüfer eine falsche Information zu geben und einen dynamischen String-Wert als LiteralString auszugeben. Das Gleiche gilt für eine Variable vom Typ Any.

3. Kommentare wie # type: ignore könnten verwendet werden, um Warnungen über Nicht-Literal-Strings zu ignorieren.

4. Triviale Funktionen könnten konstruiert werden, um einen str in einen LiteralString zu konvertieren.

 def make_literal(s: str) -> LiteralString:
     letters: Dict[str, LiteralString] = {
         "A": "A",
         "B": "B",
         ...
     }
     output: List[LiteralString] = [letters[c] for c in s]
     return "".join(output)

Wir könnten die oben genannten Punkte durch Linting, Code-Reviews usw. abmildern, aber letztendlich wird ein cleverer, böswilliger Entwickler, der versucht, die von LiteralString angebotenen Schutzmechanismen zu umgehen, immer erfolgreich sein. Wichtig ist zu bedenken, dass LiteralString nicht dazu gedacht ist, vor *bösartigen* Entwicklern zu schützen; es soll vor gutmütigen Entwicklern schützen, die versehentlich sensible APIs auf gefährliche Weise verwenden (ohne sie anderweitig zu behindern).

Ohne LiteralString ist das beste Werkzeug zur Durchsetzung, das API-Autoren zur Verfügung steht, die Dokumentation, die leicht ignoriert und oft nicht gelesen wird. Mit LiteralString erfordert API-Missbrauch bewusste Gedanken und Artefakte im Code, die Prüfer und zukünftige Entwickler bemerken können.

Anhang C: str-Methoden, die LiteralString beibehalten

Die str-Klasse hat mehrere Methoden, die von LiteralString profitieren würden. Zum Beispiel könnten Benutzer erwarten, dass "hello".capitalize() den Typ LiteralString hat, ähnlich wie die anderen Beispiele, die wir im Abschnitt Inferring LiteralString gesehen haben. Die Inferenz des Typs LiteralString ist korrekt, da der String kein beliebiger, vom Benutzer bereitgestellter String ist – wir wissen, dass er den Typ Literal["HELLO"] hat, der mit LiteralString kompatibel ist. Mit anderen Worten, die Methode capitalize erhält den Typ LiteralString. Es gibt mehrere andere str-Methoden, die LiteralString erhalten.

Wir schlagen vor, den Stub für str in typeshed zu aktualisieren, damit die Methoden mit den LiteralString-erhaltenden Versionen überladen werden. Das bedeutet, dass Typüberprüfer das LiteralString-Verhalten für jede Methode nicht hartkodieren müssen. Außerdem können wir so zukünftige Methoden einfach durch Aktualisieren des typeshed-Stubs unterstützen.

Zum Beispiel würden wir zum Erhalten von literalen Typen für die capitalize-Methode den Stub wie folgt ändern

# before
def capitalize(self) -> str: ...

# after
@overload
def capitalize(self: LiteralString) -> LiteralString: ...
@overload
def capitalize(self) -> str: ...

Der Nachteil der Änderung des str-Stubs ist, dass der Stub komplizierter wird und Fehlermeldungen schwerer verständlich machen kann. Typüberprüfer müssen str möglicherweise speziell behandeln, um Fehlermeldungen für Benutzer verständlich zu machen.

Unten finden Sie eine vollständige Liste von str-Methoden, die, wenn sie mit Argumenten vom Typ LiteralString aufgerufen werden, als Rückgabe eines LiteralString behandelt werden müssen. Wenn dieser PEP akzeptiert wird, werden wir diese Methodensignaturen in typeshed aktualisieren.

@overload
def capitalize(self: LiteralString) -> LiteralString: ...
@overload
def capitalize(self) -> str: ...

@overload
def casefold(self: LiteralString) -> LiteralString: ...
@overload
def casefold(self) -> str: ...

@overload
def center(self: LiteralString, __width: SupportsIndex, __fillchar: LiteralString = ...) -> LiteralString: ...
@overload
def center(self, __width: SupportsIndex, __fillchar: str = ...) -> str: ...

if sys.version_info >= (3, 8):
    @overload
    def expandtabs(self: LiteralString, tabsize: SupportsIndex = ...) -> LiteralString: ...
    @overload
    def expandtabs(self, tabsize: SupportsIndex = ...) -> str: ...

else:
    @overload
    def expandtabs(self: LiteralString, tabsize: int = ...) -> LiteralString: ...
    @overload
    def expandtabs(self, tabsize: int = ...) -> str: ...

@overload
def format(self: LiteralString, *args: LiteralString, **kwargs: LiteralString) -> LiteralString: ...
@overload
def format(self, *args: str, **kwargs: str) -> str: ...

@overload
def join(self: LiteralString, __iterable: Iterable[LiteralString]) -> LiteralString: ...
@overload
def join(self, __iterable: Iterable[str]) -> str: ...

@overload
def ljust(self: LiteralString, __width: SupportsIndex, __fillchar: LiteralString = ...) -> LiteralString: ...
@overload
def ljust(self, __width: SupportsIndex, __fillchar: str = ...) -> str: ...

@overload
def lower(self: LiteralString) -> LiteralString: ...
@overload
def lower(self) -> LiteralString: ...

@overload
def lstrip(self: LiteralString, __chars: LiteralString | None = ...) -> LiteralString: ...
@overload
def lstrip(self, __chars: str | None = ...) -> str: ...

@overload
def partition(self: LiteralString, __sep: LiteralString) -> tuple[LiteralString, LiteralString, LiteralString]: ...
@overload
def partition(self, __sep: str) -> tuple[str, str, str]: ...

@overload
def replace(self: LiteralString, __old: LiteralString, __new: LiteralString, __count: SupportsIndex = ...) -> LiteralString: ...
@overload
def replace(self, __old: str, __new: str, __count: SupportsIndex = ...) -> str: ...

if sys.version_info >= (3, 9):
    @overload
    def removeprefix(self: LiteralString, __prefix: LiteralString) -> LiteralString: ...
    @overload
    def removeprefix(self, __prefix: str) -> str: ...

    @overload
    def removesuffix(self: LiteralString, __suffix: LiteralString) -> LiteralString: ...
    @overload
    def removesuffix(self, __suffix: str) -> str: ...

@overload
def rjust(self: LiteralString, __width: SupportsIndex, __fillchar: LiteralString = ...) -> LiteralString: ...
@overload
def rjust(self, __width: SupportsIndex, __fillchar: str = ...) -> str: ...

@overload
def rpartition(self: LiteralString, __sep: LiteralString) -> tuple[LiteralString, LiteralString, LiteralString]: ...
@overload
def rpartition(self, __sep: str) -> tuple[str, str, str]: ...

@overload
def rsplit(self: LiteralString, sep: LiteralString | None = ..., maxsplit: SupportsIndex = ...) -> list[LiteralString]: ...
@overload
def rsplit(self, sep: str | None = ..., maxsplit: SupportsIndex = ...) -> list[str]: ...

@overload
def rstrip(self: LiteralString, __chars: LiteralString | None = ...) -> LiteralString: ...
@overload
def rstrip(self, __chars: str | None = ...) -> str: ...

@overload
def split(self: LiteralString, sep: LiteralString | None = ..., maxsplit: SupportsIndex = ...) -> list[LiteralString]: ...
@overload
def split(self, sep: str | None = ..., maxsplit: SupportsIndex = ...) -> list[str]: ...

@overload
def splitlines(self: LiteralString, keepends: bool = ...) -> list[LiteralString]: ...
@overload
def splitlines(self, keepends: bool = ...) -> list[str]: ...

@overload
def strip(self: LiteralString, __chars: LiteralString | None = ...) -> LiteralString: ...
@overload
def strip(self, __chars: str | None = ...) -> str: ...

@overload
def swapcase(self: LiteralString) -> LiteralString: ...
@overload
def swapcase(self) -> str: ...

@overload
def title(self: LiteralString) -> LiteralString: ...
@overload
def title(self) -> str: ...

@overload
def upper(self: LiteralString) -> LiteralString: ...
@overload
def upper(self) -> str: ...

@overload
def zfill(self: LiteralString, __width: SupportsIndex) -> LiteralString: ...
@overload
def zfill(self, __width: SupportsIndex) -> str: ...

@overload
def __add__(self: LiteralString, __s: LiteralString) -> LiteralString: ...
@overload
def __add__(self, __s: str) -> str: ...

@overload
def __iter__(self: LiteralString) -> Iterator[str]: ...
@overload
def __iter__(self) -> Iterator[str]: ...

@overload
def __mod__(self: LiteralString, __x: Union[LiteralString, Tuple[LiteralString, ...]]) -> str: ...
@overload
def __mod__(self, __x: Union[str, Tuple[str, ...]]) -> str: ...

@overload
def __mul__(self: LiteralString, __n: SupportsIndex) -> LiteralString: ...
@overload
def __mul__(self, __n: SupportsIndex) -> str: ...

@overload
def __repr__(self: LiteralString) -> LiteralString: ...
@overload
def __repr__(self) -> str: ...

@overload
def __rmul__(self: LiteralString, n: SupportsIndex) -> LiteralString: ...
@overload
def __rmul__(self, n: SupportsIndex) -> str: ...

@overload
def __str__(self: LiteralString) -> LiteralString: ...
@overload
def __str__(self) -> str: ...

Anhang D: Richtlinien für die Verwendung von LiteralString in Stubs

Bibliotheken, die keine Typannotationen in ihrem Quellcode enthalten, können Typstubs in Typeshed angeben. Bibliotheken, die in anderen Sprachen geschrieben sind, wie z.B. für maschinelles Lernen, können ebenfalls Python-Typstubs bereitstellen. Das bedeutet, dass der Typüberprüfer nicht verifizieren kann, dass die Typannotationen mit dem Quellcode übereinstimmen, und dem Typstub vertrauen muss. Daher müssen Autoren von Typstubs vorsichtig sein, wenn sie LiteralString verwenden, da eine Funktion fälschlicherweise als sicher erscheinen kann, obwohl sie es nicht ist.

Wir empfehlen die folgenden Richtlinien für die Verwendung von LiteralString in Stubs

• Wenn der Stub für eine reine Funktion ist, empfehlen wir die Verwendung von LiteralString im Rückgabetyp der Funktion oder ihrer Überladungen nur dann, wenn alle entsprechenden Parameter literale Typen haben (d.h. LiteralString oder Literal["a", "b"]).

  # OK
  @overload
  def my_transform(x: LiteralString, y: Literal["a", "b"]) -> LiteralString: ...
  @overload
  def my_transform(x: str, y: str) -> str: ...
  
  # Not OK
  @overload
  def my_transform(x: LiteralString, y: str) -> LiteralString: ...
  @overload
  def my_transform(x: str, y: str) -> str: ...
  

• Wenn der Stub für eine staticmethod ist, empfehlen wir die gleiche Richtlinie wie oben.
• Wenn der Stub für eine andere Art von Methode ist, raten wir von der Verwendung von LiteralString im Rückgabetyp der Methode oder einer ihrer Überladungen ab. Dies liegt daran, dass auch wenn alle expliziten Parameter den Typ LiteralString haben, das Objekt selbst möglicherweise unter Verwendung von Benutzerdaten erstellt wurde und somit der Rückgabetyp benutzergesteuert sein kann.
• Wenn der Stub für ein Klassenattribut oder eine globale Variable ist, raten wir ebenfalls von der Verwendung von LiteralString ab, da der untypisierte Code beliebige Werte in das Attribut schreiben kann.

Wir überlassen die endgültige Entscheidung jedoch dem Autor der Bibliothek. Er kann LiteralString verwenden, wenn er zuversichtlich ist, dass der von der Methode oder Funktion zurückgegebene String oder der im Attribut gespeicherte String garantiert einen literalen Typ hat – d.h. der String wird durch Anwenden von nur literale-erhaltenden str-Operationen auf einen String-Literal erstellt.

Beachten Sie, dass diese Richtlinien nicht für Inline-Typannotationen gelten, da der Typüberprüfer verifizieren kann, dass beispielsweise eine Methode, die LiteralString zurückgibt, tatsächlich einen Ausdruck dieses Typs zurückgibt.

Ressourcen

Urheberrecht

Dieses Dokument wird in die Public Domain oder unter die CC0-1.0-Universal-Lizenz gestellt, je nachdem, welche Lizenz permissiver ist.