Stub file syntax

Stub files are written in normal Python 3 syntax, but generallyleaving out runtime logic like variable initializers, function bodies,and default arguments.

If it is not possible to completely leave out some piece of runtimelogic, the recommended convention is to replace or elide them with ellipsisexpressions (…). Each ellipsis below is literally written in thestub file as three dots:

  1. # Variables with annotations do not need to be assigned a value.
  2. # So by convention, we omit them in the stub file.
  3. x: int
  4.  
  5. # Function bodies cannot be completely removed. By convention,
  6. # we replace them with `...` instead of the `pass` statement.
  7. def func_1(code: str) -> int: ...
  8.  
  9. # We can do the same with default arguments.
  10. def func_2(a: int, b: int = ...) -> int: ...

Note

The ellipsis … is also used with a different meaning incallable types and tuple types.

Note

It is always legal to use Python 3 syntax in stub files, even whenwriting Python 2 code. The example above is a valid stub filefor both Python 2 and 3.