Skip to content

Commit

Permalink
Suggest to use _ prefix for stubs-only types (python#1005)
Browse files Browse the repository at this point in the history
  • Loading branch information
sobolevn authored Jan 4, 2022
1 parent fbd81cd commit 2370371
Showing 1 changed file with 7 additions and 3 deletions.
10 changes: 7 additions & 3 deletions docs/source/stubs.rst
Original file line number Diff line number Diff line change
Expand Up @@ -577,19 +577,21 @@ public method for which a library does not provided a usable runtime type::

from typing import Protocol

class Readable(Protocol):
class _Readable(Protocol):
def read(self) -> str: ...

def get_reader() -> Readable: ...
def get_reader() -> _Readable: ...

Structural Types
----------------

As seen in the example with ``Readable`` in the previous section, a common use
As seen in the example with ``_Readable`` in the previous section, a common use
of stub-only objects is to model types that are best described by their
structure. These objects are called protocols [#pep544]_, and it is encouraged
to use them freely to describe simple structural types.

It is `recommended <private-definitions>`_ to prefix stubs-only object names with ``_``.

Incomplete Stubs
----------------

Expand Down Expand Up @@ -921,6 +923,8 @@ No::
...
def to_int3(x: str) -> int: pass

.. _private-definitions:

Private Definitions
-------------------

Expand Down

0 comments on commit 2370371

Please sign in to comment.