PEP 675: fix wording in a couple of places (#2326)

+ Add newlines to make code samples easier to read.
+ s/argument/parameter/.
This commit is contained in:
Pradeep Kumar 2022-02-15 17:08:01 -08:00 committed by GitHub
parent 918f3dfc9f
commit 49ec965e65
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 14 additions and 11 deletions

View File

@ -389,8 +389,10 @@ Addition of literal strings:
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.
@ -401,6 +403,7 @@ Join using literal strings:
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]))
@ -843,10 +846,10 @@ shell command:
subprocess.run(f"echo 'Hello {name}'", shell=True)
If attacker controlled data is included in the command string, a
command injection vulnerability exists and malicious operations can be
run. For example, a value of ``' && rm -rf / #`` would result in the
following destructive command being run:
If user-controlled data is included in the command string, the code is
vulnerable to "command injection", i.e., an attacker can run malicious
commands. For example, a value of ``' && rm -rf / #`` would result in
the following destructive command being run:
::
@ -1044,10 +1047,10 @@ more complicated and can make error messages harder to
understand. Type checkers may need to special-case ``str`` to make
error messages understandable for users.
Below is an exhaustive list of ``str`` methods which, when called as
indicated with arguments of type ``LiteralString``, must be treated as
returning a ``LiteralString``. If this PEP is accepted, we will update
these method signatures in typeshed:
Below is an exhaustive list of ``str`` methods which, when called with
arguments of type ``LiteralString``, must be treated as returning a
``LiteralString``. If this PEP is accepted, we will update these
method signatures in typeshed:
::
@ -1223,14 +1226,14 @@ specify type stubs in Typeshed. Libraries written in other languages,
such as those for machine learning, may also provide Python type
stubs. This means the type checker cannot verify that the type
annotations match the source code and must trust the type stub. Thus,
authors of type stubs need to be careful when using ``LiteralString``
authors of type stubs need to be careful when using ``LiteralString``,
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 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.,
the corresponding parameters have literal types (i.e.,
``LiteralString`` or ``Literal["a", "b"]``).
::
@ -1252,7 +1255,7 @@ We recommend the following guidelines for using ``LiteralString`` in stubs:
+ If the stub is for any other kind of method, we recommend against
using ``LiteralString`` in the return type of the method or any of
its overloads. This is because, even if all the explicit arguments
its overloads. This is because, even if all the explicit parameters
have type ``LiteralString``, the object itself may be created using
user data and thus the return type may be user-controlled.