StarMirror/styleguide
1
0
Fork 0
mirror of https://github.com/google/styleguide.git synced 2024-03-22 13:11:43 +08:00
Code Issues Projects Releases Wiki Activity

Project import generated by Copybara.

Browse Source 
PiperOrigin-RevId: 606308053
This commit is contained in:
Google Python team 2024-02-12 11:14:45 -08:00 committed by Gregory P. Smith [Google LLC]
parent 1ec490aaef
commit 8ee3431f74
1 changed files with 18 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
pyguide.md
View File

@ -405,13 +405,16 @@ Exceptions must follow certain conditions:
- Make use of built-in exception classes when it makes sense. For example, - Make use of built-in exception classes when it makes sense. For example,
raise a `ValueError` to indicate a programming mistake like a violated raise a `ValueError` to indicate a programming mistake like a violated
precondition (such as if you were passed a negative number but required a precondition, such as may happen when validating function arguments.
positive one). Do not use `assert` statements for validating argument values
of a public API. `assert` is used to ensure internal correctness or - Do not use `assert` statements in place of conditionals or validating
to verify expectations in preconditions. They must not be critical to the application logic. A litmus
[pytest](https://pytest.org) based tests, not to enforce correct usage nor test would be that the `assert` could be removed without breaking the code.
to indicate that some unexpected event occurred. If an exception is desired `assert` conditionals are
in the latter cases, use a raise statement. For example: [not guaranteed](https://docs.python.org/3/reference/simple_stmts.html#the-assert-statement)
to be evaluated. For [pytest](https://pytest.org) based tests, `assert` is
okay and expected to verify expectations. For
example:
```python ```python
@ -437,6 +440,7 @@ Exceptions must follow certain conditions:
if port is None: if port is None:
raise ConnectionError( raise ConnectionError(
f'Could not connect to service on port {minimum} or higher.') f'Could not connect to service on port {minimum} or higher.')
# The code does not depend on the result of this assert.
assert port >= minimum, ( assert port >= minimum, (
f'Unexpected port {port} when minimum was {minimum}.') f'Unexpected port {port} when minimum was {minimum}.')
return port return port
@ -454,8 +458,10 @@ Exceptions must follow certain conditions:
The new minimum port. The new minimum port.
""" """
assert minimum >= 1024, 'Minimum port must be at least 1024.' assert minimum >= 1024, 'Minimum port must be at least 1024.'
# The following code depends on the previous assert.
port = self._find_next_open_port(minimum) port = self._find_next_open_port(minimum)
assert port is not None assert port is not None
# The type checking of the return statement relies on the assert.
return port return port
``` ```
@ -2240,8 +2246,8 @@ class Child(Parent):
#### 3.8.4 Classes #### 3.8.4 Classes
Classes should have a docstring below the class definition describing the class. Classes should have a docstring below the class definition describing the class.
If your class has public attributes, they should be documented here in an Public attributes, excluding [properties](#properties), should be documented
`Attributes` section and follow the same formatting as a here in an `Attributes` section and follow the same formatting as a
[function's `Args`](#doc-function-args) section. [function's `Args`](#doc-function-args) section.
```python ```python
@ -2265,8 +2271,9 @@ class SampleClass:
self.likes_spam = likes_spam self.likes_spam = likes_spam
self.eggs = 0 self.eggs = 0
def public_method(self): @property
"""Performs operation blah.""" def butter_sticks(self) -> int:
"""The number of butter sticks we have."""
``` ```
All class docstrings should start with a one-line summary that describes what All class docstrings should start with a one-line summary that describes what