Minor formatting and wording fixes (#2293)

This commit is contained in:
Graham Bleaney 2022-02-02 07:49:27 -05:00 committed by GitHub
parent 49cf033720
commit 74272d5238
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 8 additions and 9 deletions

View File

@ -363,13 +363,12 @@ See the examples below to help clarify the above rules:
literal_string: LiteralString = s # Error: Expected LiteralString, got str.
literal_string: LiteralString = "hello" # OK
def expect_literal_string(s: LiteralString) -> None: ...
Addition of literal strings:
::
def expect_literal_string(s: LiteralString) -> None: ...
expect_literal_string("foo" + "bar") # OK
expect_literal_string(literal_string + "bar") # OK
literal_string2: LiteralString
@ -387,7 +386,7 @@ Join using literal strings:
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``.
# Not OK because the separator has type 'str'.
In-place addition using literal strings:
@ -409,9 +408,10 @@ Format strings using literal strings:
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``.
# NOT OK. The format-string is constructed from 'username',
# which has type 'str'.
expect_literal_string("hello {}".format(username)) # Not OK
@ -542,7 +542,7 @@ string, the following example should be OK:
x = "hello"
expect_literal_string(x)
# OK, because x is inferred to have type ``Literal["hello"]``.
# OK, because x is inferred to have type 'Literal["hello"]'.
This enables precise type checking of idiomatic SQL query code without
annotating the code at all (as seen in the `Motivation`_ section
@ -664,7 +664,6 @@ system, such as ``NewType("SafeSQL", str)``:
SafeSQL = NewType("SafeSQL", str)
def execute(self, sql: SafeSQL, parameters: Iterable[str] = ...) -> Cursor: ...
execute(SafeSQL("SELECT * FROM data WHERE user_id = ?"), user_id) # OK
@ -1216,7 +1215,7 @@ since a function may falsely appear to be safe when it is not.
We recommend the following guidelines for using ``LiteralString`` in stubs:
+ If the stub is for a function, we recommend using ``LiteralString``
+ If the stub is for a pure function, we recommend using ``LiteralString``
in the return type of the function or of its overloads only if all
the corresponding arguments have literal types (i.e.,
``LiteralString`` or ``Literal["a", "b"]``).