From 2370371c7258f0b1432c34498ad742783503750d Mon Sep 17 00:00:00 2001 From: Nikita Sobolev Date: Tue, 4 Jan 2022 21:14:39 +0300 Subject: [PATCH] Suggest to use `_` prefix for stubs-only types (#1005) --- docs/source/stubs.rst | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/source/stubs.rst b/docs/source/stubs.rst index d5ad68506..ae4567052 100644 --- a/docs/source/stubs.rst +++ b/docs/source/stubs.rst @@ -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 `_ to prefix stubs-only object names with ``_``. + Incomplete Stubs ---------------- @@ -921,6 +923,8 @@ No:: ... def to_int3(x: str) -> int: pass +.. _private-definitions: + Private Definitions -------------------