Yes: foo_bar(self, width, height, color='black', design=None, x='foo',
             emphasis=None, highlight=0)

 
Yes: if (width == 0 and height == 0 and
         color == 'red' and emphasis == 'strong'):
 
     (bridge_questions.clarification_on
      .average_airspeed_of.unladen_swallow) = 'African or European?'
 
     with (
         very_long_first_expression_function() as spam,
         very_long_second_expression_function() as beans,
         third_thing() as eggs,
     ):
       place_order(eggs, beans, spam, beans)

 
No:  if width == 0 and height == 0 and \
         color == 'red' and emphasis == 'strong':
 
     bridge_questions.clarification_on \
         .average_airspeed_of.unladen_swallow = 'African or European?'
 
     with very_long_first_expression_function() as spam, \
           very_long_second_expression_function() as beans, \
           third_thing() as eggs:
       place_order(eggs, beans, spam, beans)

x = ('This will build a very long long '
     'long long long long long long string')

Yes: bridgekeeper.answer(
         name="Arthur", quest=questlib.find(owner="Arthur", perilous=True))
 
     answer = (a_long_line().of_chained_methods()
               .that_eventually_provides().an_answer())
 
     if (
         config is None
         or 'editor.language' not in config
         or config['editor.language'].use_spaces is False
     ):
       use_tabs()

No: bridgekeeper.answer(name="Arthur", quest=questlib.find(
        owner="Arthur", perilous=True))
 
    answer = a_long_line().of_chained_methods().that_eventually_provides(
        ).an_answer()
 
    if (config is None or 'editor.language' not in config or config[
        'editor.language'].use_spaces is False):
      use_tabs()
 

Yes:  # See details at
      # http://www.example.com/us/developer/documentation/api/content/v2.0/csv_file_name_extension_full_specification.html

No:  # See details at
     # http://www.example.com/us/developer/documentation/api/content/\
     # v2.0/csv_file_name_extension_full_specification.html

Yes: if foo:
         bar()
     while x:
         x = bar()
     if x and y:
         bar()
     if not x:
         bar()
     # 对于单元素元组，()s 比逗号更直观。
     onesie = (foo,)
     return foo
     return spam, beans
     return (spam, beans)
     for (x, y) in dict.items(): ...

No:  if (x):
         bar()
     if not(x):
         bar()
     return (foo)

Yes:   # 与开始分隔符对齐。
       foo = long_function_name(var_one, var_two,
                                var_three, var_four)
       meal = (spam,
               beans)
 
       # 字典中与开始分隔符对齐。
       foo = {
           'long_dictionary_key': value1 +
                                  value2,
           ...
       }
 
       # 4 空格悬挂缩进；第一行不放内容。
       foo = long_function_name(
           var_one, var_two, var_three,
           var_four)
       meal = (
           spam,
           beans)
 
       # 4 空格悬挂缩进；第一行不放内容，
       # 闭合括号另起一行。
       foo = long_function_name(
           var_one, var_two, var_three,
           var_four
       )
       meal = (
           spam,
           beans,
       )
 
       # 字典中的 4 空格悬挂缩进。
       foo = {
           'long_dictionary_key':
               long_dictionary_value,
           ...
       }

No:    # 第一行不应有内容。
       foo = long_function_name(var_one, var_two,
           var_three, var_four)
       meal = (spam,
           beans)
 
       # 不允许 2 空格悬挂缩进。
       foo = long_function_name(
         var_one, var_two, var_three,
         var_four)
 
       # 字典中没有悬挂缩进。
       foo = {
           'long_dictionary_key':
           long_dictionary_value,
           ...
       }

Yes:   golomb3 = [0, 1, 3]
       golomb4 = [
           0,
           1,
           4,
           6,
       ]

No:    golomb4 = [
           0,
           1,
           4,
           6,]

Yes: spam(ham[1], {'eggs': 2}, [])

No:  spam( ham[ 1 ], { 'eggs': 2 }, [ ] )

Yes: if x == 4:
         print(x, y)
     x, y = y, x

No:  if x == 4 :
         print(x , y)
     x , y = y , x

Yes: spam(1)

No:  spam (1)

Yes: dict['key'] = list[index]

No:  dict ['key'] = list [index]

Yes: x == 1

No:  x<1

Yes: def complex(real, imag=0.0): return Magic(r=real, i=imag)
Yes: def complex(real, imag: float = 0.0): return Magic(r=real, i=imag)

No:  def complex(real, imag = 0.0): return Magic(r = real, i = imag)
No:  def complex(real, imag: float=0.0): return Magic(r = real, i = imag)

Yes:
  foo = 1000  # comment
  long_name = 2  # comment that should not be aligned
 
  dictionary = {
      'foo': 1,
      'long_name': 2,
  }

No:
  foo       = 1000  # comment
  long_name = 2     # comment that should not be aligned
 
  dictionary = {
      'foo'      : 1,
      'long_name': 2,
  }

"""A one-line summary of the module or program, terminated by a period.
 
Leave one blank line.  The rest of this docstring should contain an
overall description of the module or program.  Optionally, it may also
contain a brief description of exported classes and functions and/or usage
examples.
 
Typical usage example:
 
  foo = ClassFoo()
  bar = foo.function_bar()
"""

"""This blaze test uses golden files.
 
You can update those files by running
`blaze run //foo/bar:foo_test -- --update_golden_files` from the `google3`
directory.
"""

"""Tests for foo.bar."""

def fetch_smalltable_rows(
    table_handle: smalltable.Table,
    keys: Sequence[bytes | str],
    require_all_keys: bool = False,
) -> Mapping[bytes, tuple[str, ...]]:
    """Fetches rows from a Smalltable.
 
    Retrieves rows pertaining to the given keys from the Table instance
    represented by table_handle.  String keys will be UTF-8 encoded.
 
    Args:
        table_handle: An open smalltable.Table instance.
        keys: A sequence of strings representing the key of each table
          row to fetch.  String keys will be UTF-8 encoded.
        require_all_keys: If True only rows with values set for all keys will be
          returned.
 
    Returns:
        A dict mapping keys to the corresponding table row data
        fetched. Each row is represented as a tuple of strings. For
        example:
 
        {b'Serak': ('Rigel VII', 'Preparer'),
         b'Zim': ('Irk', 'Invader'),
         b'Lrrr': ('Omicron Persei 8', 'Emperor')}
 
        Returned keys are always bytes.  If a key from the keys argument is
        missing from the dictionary, then that row was not found in the
        table (and require_all_keys must have been False).
 
    Raises:
        IOError: An error occurred accessing the smalltable.
    """

def fetch_smalltable_rows(
    table_handle: smalltable.Table,
    keys: Sequence[bytes | str],
    require_all_keys: bool = False,
) -> Mapping[bytes, tuple[str, ...]]:
    """Fetches rows from a Smalltable.
 
    Retrieves rows pertaining to the given keys from the Table instance
    represented by table_handle.  String keys will be UTF-8 encoded.
 
    Args:
      table_handle:
        An open smalltable.Table instance.
      keys:
        A sequence of strings representing the key of each table row to
        fetch.  String keys will be UTF-8 encoded.
      require_all_keys:
        If True only rows with values set for all keys will be returned.
 
    Returns:
      A dict mapping keys to the corresponding table row data
      fetched. Each row is represented as a tuple of strings. For
      example:
 
      {b'Serak': ('Rigel VII', 'Preparer'),
       b'Zim': ('Irk', 'Invader'),
       b'Lrrr': ('Omicron Persei 8', 'Emperor')}
 
      Returned keys are always bytes.  If a key from the keys argument is
      missing from the dictionary, then that row was not found in the
      table (and require_all_keys must have been False).
 
    Raises:
      IOError: An error occurred accessing the smalltable.
    """

from typing_extensions import override
 
class Parent:
  def do_something(self):
    """Parent method, includes docstring."""
 
# 子类，方法用 override 注解。
class Child(Parent):
  @override
  def do_something(self):
    pass

# 子类，但没有 @override 装饰器，需要文档字符串。
class Child(Parent):
  def do_something(self):
    pass
 
# 琐碎的文档字符串是不需要的，@override 足以表明文档可在基类中找到。
class Child(Parent):
  @override
  def do_something(self):
    """See base class."""

class SampleClass:
    """Summary of class here.
 
    Longer class information...
    Longer class information...
 
    Attributes:
        likes_spam: A boolean indicating if we like SPAM or not.
        eggs: An integer count of the eggs we have laid.
    """
 
    def __init__(self, likes_spam: bool = False):
        """Initializes the instance based on spam preference.
 
        Args:
          likes_spam: Defines if instance exhibits this preference.
        """
        self.likes_spam = likes_spam
        self.eggs = 0
 
    @property
    def butter_sticks(self) -> int:
        """The number of butter sticks we have."""

# Yes:
class CheeseShopAddress:
  """The address of a cheese shop.
 
  ...
  """
 
class OutOfCheeseError(Exception):
  """No more cheese is available."""

# No:
class CheeseShopAddress:
  """Class that describes the address of a cheese shop.
 
  ...
  """
 
class OutOfCheeseError(Exception):
  """Raised when no more cheese is available."""

# We use a weighted dictionary search to find out where i is in
# the array.  We extrapolate position based on the largest num
# in the array and the array size and then do binary search to
# get the exact number.
 
if i & (i-1) == 0:  # True if i is 0 or a power of 2.

# BAD COMMENT: Now go through the b array and make sure whenever i occurs
# the next element is i+1

Yes: x = f'name: {name}; score: {n}'
     x = '%s, %s!' % (imperative, expletive)
     x = '{}, {}'.format(first, second)
     x = 'name: %s; score: %d' % (name, n)
     x = 'name: %(name)s; score: %(score)d' % {'name':name, 'score':n}
     x = 'name: {}; score: {}'.format(name, n)
     x = a + b

No: x = first + ', ' + second
    x = 'name: ' + name + '; score: ' + str(n)

Yes: items = ['<table>']
     for last_name, first_name in employee_list:
         items.append('<tr><td>%s, %s</td></tr>' % (last_name, first_name))
     items.append('</table>')
     employee_table = ''.join(items)

No: employee_table = '<table>'
    for last_name, first_name in employee_list:
        employee_table += '<tr><td>%s, %s</td></tr>' % (last_name, first_name)
    employee_table += '</table>'

Yes:
  Python('Why are you hiding your eyes?')
  Gollum("I'm scared of lint errors.")
  Narrator('"Good!" thought a happy Python reviewer.')

No:
  Python("Why are you hiding your eyes?")
  Gollum('The lint. It burns. It burns us.')
  Gollum("Always the great lint. Watching. Watching.")

  No:
  long_string = """This is pretty ugly.
Don't do this.
"""

  Yes:
  long_string = """This is fine if your use case can accept
      extraneous leading spaces."""

  Yes:
  long_string = ("And this is fine if you cannot accept\n" +
                 "extraneous leading spaces.")

  Yes:
  long_string = ("And this too is fine if you cannot accept\n"
                 "extraneous leading spaces.")

  Yes:
  import textwrap
 
  long_string = textwrap.dedent("""\
      This is also fine, because textwrap.dedent()
      will collapse common leading spaces in each line.""")

  Yes:
  import tensorflow as tf
  logger = tf.get_logger()
  logger.info('TensorFlow Version is: %s', tf.__version__)

  Yes:
  import os
  from absl import logging
 
  logging.info('Current $PAGER is: %s', os.getenv('PAGER', default=''))
 
  homedir = os.getenv('HOME')
  if homedir is None or not os.access(homedir, os.W_OK):
    logging.error('Cannot write to home directory, $HOME=%r', homedir)

  No:
  import os
  from absl import logging
 
  logging.info('Current $PAGER is:')
  logging.info(os.getenv('PAGER', default=''))
 
  homedir = os.getenv('HOME')
  if homedir is None or not os.access(homedir, os.W_OK):
    logging.error(f'Cannot write to home directory, $HOME={homedir!r}')

  Yes:
  if not 0 <= p <= 1:
    raise ValueError(f'Not a probability: {p=}')
 
  try:
    os.rmdir(workdir)
  except OSError as error:
    logging.warning('Could not remove directory (reason: %r): %r',
                    error, workdir)

  No:
  if p < 0 or p > 1:  # PROBLEM: also false for float('nan')!
    raise ValueError(f'Not a probability: {p=}')
 
  try:
    os.rmdir(workdir)
  except OSError:
    # PROBLEM: Message makes an assumption that might not be true:
    # Deletion might have failed for some other reason, misleading
    # whoever has to debug this.
    logging.warning('Directory already was deleted: %s', workdir)
 
  try:
    os.rmdir(workdir)
  except OSError:
    # PROBLEM: The message is harder to grep for than necessary, and
    # not universally non-confusing for all possible values of `workdir`.
    # Imagine someone calling a library function with such code
    # using a name such as workdir = 'deleted'. The warning would read:
    # "The deleted directory could not be deleted."
    logging.warning('The %s directory could not be deleted.', workdir)

with open("hello.txt") as hello_file:
    for line in hello_file:
        print(line)

import contextlib
 
with contextlib.closing(urllib.urlopen("http://www.python.org/")) as front_page:
    for line in front_page:
        print(line)

# TODO: crbug.com/192795 - Investigate cpufreq optimizations.

# TODO(crbug.com/192795): Investigate cpufreq optimizations.
# TODO(yourusername): Use a "\*" here for concatenation operator.

# TODO: @yourusername - File an issue and use a '*' for repetition.

Yes: from collections.abc import Mapping, Sequence
     import os
     import sys
     from typing import Any, NewType

No:  import os, sys

import collections
import queue
import sys
 
from absl import app
from absl import flags
import bs4
import cryptography
import tensorflow as tf
 
from book.genres import scifi
from myproject.backend import huxley
from myproject.backend.hgwells import time_machine
from myproject.backend.state_machine import main_loop
from otherproject.ai import body
from otherproject.ai import mind
from otherproject.ai import soul
 
# Older style code may have these imports down here instead:
#from myproject.backend.hgwells import time_machine
#from myproject.backend.state_machine import main_loop

Yes:
 
  if foo: bar(foo)

No:
 
  if foo: bar(foo)
  else:   baz(foo)
 
  try:               bar(foo)
  except ValueError: baz(foo)
 
  try:
      bar(foo)
  except ValueError: baz(foo)

from absl import app
...
 
def main(argv: Sequence[str]):
    # process non-flag arguments
    ...
 
if __name__ == '__main__':
    app.run(main)

def main():
    ...
 
if __name__ == '__main__':
    main()

def my_method(
    self,
    first_var: int,
    second_var: Foo,
    third_var: Bar | None,
) -> int:
  ...

def my_method(self, first_var: int) -> int:
  ...

Yes:
def my_method(
    self,
    other_arg: MyLongType | None,
) -> tuple[MyLongType1, MyLongType1]:
  ...

Okay:
def my_method(
    self,
    first_var: int,
    second_var: int) -> dict[OtherLongType, MyLongType]:
  ...

No:
def my_method(self,
              other_arg: MyLongType | None,
             ) -> dict[OtherLongType, MyLongType]:
  ...

def my_method(
    self,
    first_var: tuple[list[MyLongType1],
                     list[MyLongType2]],
    second_var: list[dict[
        MyLongType3, MyLongType4]],
) -> None:
  ...

Yes:
def my_function(
    long_variable_name:
        long_module_name.LongTypeName,
) -> None:
  ...

No:
def my_function(
    long_variable_name: long_module_name.
        LongTypeName,
) -> None:
  ...

Yes:
from __future__ import annotations
 
class MyClass:
  def __init__(self, stack: Sequence[MyClass], item: OtherClass) -> None:
 
class OtherClass:
  ...

Yes:
class MyClass:
  def __init__(self, stack: Sequence['MyClass'], item: 'OtherClass') -> None:
 
class OtherClass:
  ...

Yes:
def func(a: int = 0) -> int:
  ...

No:
def func(a:int=0) -> int:
  ...

Yes:
def modern_or_union(a: str | int | None, b: str | None = None) -> str:
  ...
def union_optional(a: Union[str, int, None], b: Optional[str] = None) -> str:
  ...

No:
def nullable_union(a: Union[None, str]) -> str:
  ...
def implicit_optional(a: str = None) -> str:
  ...

from typing import TypeAlias
 
_LossAndGradient: TypeAlias = tuple[tf.Tensor, tf.Tensor]
ComplexTFMap: TypeAlias = Mapping[str, _LossAndGradient]

# pytype: disable=attribute-error

```python
a: Foo = SomeUndecoratedFunction()
```

```python
a = SomeUndecoratedFunction()  # type: Foo
```

a: list[int] = [1, 2, 3]
b: tuple[int, ...] = (1, 2, 3)
c: tuple[int, str, float] = (1, "2", 3.5)

from collections.abc import Callable
from typing import ParamSpec, TypeVar
_P = ParamSpec("_P")
_T = TypeVar("_T")
...
def next(l: list[_T]) -> _T:
  return l.pop()
 
def print_when_called(f: Callable[_P, _T]) -> Callable[_P, _T]:
  def inner(*args: _P.args, **kwargs: _P.kwargs) -> _T:
    print("Function was called")
    return f(*args, **kwargs)
  return inner

AddableType = TypeVar("AddableType", int, float, str)
def add(a: AddableType, b: AddableType) -> AddableType:
  return a + b

from typing import AnyStr
def check_length(x: AnyStr) -> AnyStr:
  if len(x) <= 42:
    return x
  raise ValueError()

Yes:
  _T = TypeVar("_T")
  _P = ParamSpec("_P")
  AddableType = TypeVar("AddableType", int, float, str)
  AnyFunction = TypeVar("AnyFunction", bound=Callable)

No:
  T = TypeVar("T")
  P = ParamSpec("P")
  _T = TypeVar("_T", int, float, str)
  _F = TypeVar("_F", bound=Callable)

def deals_with_text_data(x: str) -> str:
  ...
def deals_with_binary_data(x: bytes) -> bytes:
  ...

from collections.abc import Mapping, Sequence
from typing import Any, Generic, cast, TYPE_CHECKING

from typing import Any as AnyType

from typing import List, Tuple
 
def transform_coordinates(original: List[Tuple[float, float]]) ->
    List[Tuple[float, float]]:
  ...

from collections.abc import Sequence
 
def transform_coordinates(original: Sequence[tuple[float, float]]) ->
    Sequence[tuple[float, float]]:
  ...

import typing
if typing.TYPE_CHECKING:
  import sketch
def f(x: "sketch.Sketch"): ...

from typing import Any
 
some_mod = Any  # some_mod.py imports this module.
...
 
def my_method(self, var: "some_mod.SomeType") -> None:
  ...

# Yes:
def get_names(employee_ids: Sequence[int]) -> Mapping[int, str]:
  ...

# No:
# This is interpreted as get_names(employee_ids: Sequence[Any]) -> Mapping[Any, Any]
def get_names(employee_ids: Sequence) -> Mapping:
  ...

# No:
def get_names(employee_ids: Sequence[Any]) -> Mapping[Any, str]:
  """Returns a mapping from employee ID to employee name for given IDs."""

# Yes:
_T = TypeVar('_T')
def get_names(employee_ids: Sequence[_T]) -> Mapping[_T, str]:
  """Returns a mapping from employee ID to employee name for given IDs."""