Merge the specification portion of the "Type Stubs" doc into the spec (…

…#1815)

* Type Stubs: move intro and syntax to spec.

* Moves some content into spec, deletes duplicate spec content.
* Adds placeholders for where remaining content will be moved. It will be
  split between the spec and the writing_stubs doc.

* Move "Stub Contents" to writing_stubs.

Moves the section on what to include in stubs with editorial changes only -
e.g., changing "type stub" to "stub file" to match surrounding terminology.

* Moves "Style Guide" to writing_stubs doc.

Moves the style guide with a few updates:
* Editorial changes like tweaking code examples to use recommended style.
* Attribute declarations can use assignments when needed to convey extra
  information - e.g., final attributes and enum members.
* Tweaks a reference to the double-underscore convention for positional-only
  arguments to note that it's historical.

* Change :ref:`stubs` occurrences to :ref:`stub-files`.

* Move a few "Supported Constructs" sections into spec.

The only substantive change is an update to "Comments" to note that many
formats of error suppression comments are allowed.

* Migrated "Imports" and "Module Level Attributes" supported constructs.

Added `x: Final = <literal>` to module-level attributes section.
No other changes.

* Migrate "Enums" supported construct section.

Replaces outdated info with a link to the enums section of the spec.

* Move "Classes" and "Decorators" supported constructs sections.

Added an example of an inner class to "Classes." Removed mention of
asyncio.coroutine from "Decorators" as it's very deprecated. Added functions
decorated with `@dataclass_transform` to list of decorators that type
checkers should recognize.

* Port "Functions and Methods" supported constructs section.

Removed mention of individual supported/unsupported features from this
section. Where we state that all typing features from the latest released
version are supported, added a caveat with a link to the typeshed feature
tracker.

* Adds an "Import Conventions" section (deduplication).

* Remove missed reference to deleted stubs doc.

* Fix broken refs.

* Formatting fix to docs/guides/writing_stubs.rst

Co-authored-by: Sebastian Rittau <srittau@rittau.biz>

* Reword paragraph on argument names to be more concise.

Co-authored-by: Sebastian Rittau <srittau@rittau.biz>

* Wording clarification in docs/guides/writing_stubs.rst

Co-authored-by: Sebastian Rittau <srittau@rittau.biz>

* Modernize code example in docs/guides/writing_stubs.rst

Co-authored-by: Sebastian Rittau <srittau@rittau.biz>

* Typo fix in docs/spec/distributing.rst

Co-authored-by: Sebastian Rittau <srittau@rittau.biz>

* Typo fix in docs/spec/distributing.rst

Co-authored-by: Sebastian Rittau <srittau@rittau.biz>

* Grammar fixes

* Property deleters should also be understood.

* Address future notes.

* Fix silly formatting error.

* Undelete stubs.rst.

* Address review comments.

* Reword some sections to focus on type checker behavior.
* Move or remove some sections that fit better in the writing_stubs guide or
  are redundant.

* Address more review comments.

Cuts redundant sections, moves things to writing_stubs, tries out a new
"these should be supported fully" and "these should be supported to at least
the described minimum" structure.

* Remove no-longer-needed anchor.

* And add back an accidentally deleted newline...

* Slight rewording of Decorators advice.

* Address more reviewer comments.

Moves "Library Interface" into spec, further trims redundant text.

* Remove extra colon.

* Revert changes to wrting_stubs that should be made separately.

* Delete unnecessary sentence.

Co-authored-by: Carl Meyer <carl@oddbird.net>

* Clarify some language and terminology.

* Address reviewer feedback.

* Formatting

* Drop "annotation contexts."

* Add "in annotation expressions" to newer syntax explanation.

* Update docs/spec/distributing.rst

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

* Reword syntax section.

* Update docs/spec/distributing.rst

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

* [pre-commit.ci] auto fixes from pre-commit.com hooks

---------

Co-authored-by: Sebastian Rittau <srittau@rittau.biz>
Co-authored-by: Carl Meyer <carl@oddbird.net>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

docs/guides/libraries.rst

@@ -43,7 +43,7 @@ library:
 
 Inline type annotations simply refers to the use of annotations within your
 ``.py`` files. In contrast, with type stub files, type information lives in
-separate ``.pyi`` files; see :ref:`stubs` and :ref:`writing_stubs` for more
+separate ``.pyi`` files; see :ref:`stub-files` and :ref:`writing_stubs` for more
 details.
 
 We recommend using the inline type annotations approach, since it has the
@@ -193,51 +193,8 @@ How much of my library needs types?
 A "py.typed" library should aim to be type complete so that type
 checking and inspection can work to their full extent. Here we say that a
 library is “type complete” if all of the symbols
-that comprise its interface have type annotations that refer to types
-that are fully known. Private symbols are exempt.
-
-Library interface (public and private symbols)
-----------------------------------------------
-
-If a ``py.typed`` module is present, a type checker will treat all modules
-within that package (i.e. all files that end in ``.py`` or ``.pyi``) as
-importable unless the file name begins with an underscore. These modules
-comprise the supported interface for the library.
-
-Each module exposes a set of symbols. Some of these symbols are
-considered "private” — implementation details that are not part of the
-library’s interface. Type checkers can use the following rules
-to determine which symbols are visible outside of the package.
-
-- Symbols whose names begin with an underscore (but are not dunder
- names) are considered private.
-- Imported symbols are considered private by default. If they use the
- ``import A as A`` (a redundant module alias), ``from X import A as A`` (a
- redundant symbol alias), or ``from . import A`` forms, symbol ``A`` is
- not private unless the name begins with an underscore. If a file
- ``__init__.py`` uses form ``from .A import X``, symbol ``A`` is treated
- likewise. If a wildcard import (of the form ``from X import *``) is
- used, all symbols referenced by the wildcard are not private.
-- A module can expose an ``__all__`` symbol at the module level that
- provides a list of names that are considered part of the interface.
- This overrides all other rules above, allowing imported symbols or
- symbols whose names begin with an underscore to be included in the
- interface.
-- Local variables within a function (including nested functions) are
- always considered private.
-
-The following idioms are supported for defining the values contained
-within ``__all__``. These restrictions allow type checkers to statically
-determine the value of ``__all__``.
-
-- ``__all__ = ('a', b')``
-- ``__all__ = ['a', b']``
-- ``__all__ += ['a', b']``
-- ``__all__ += submodule.__all__``
-- ``__all__.extend(['a', b'])``
-- ``__all__.extend(submodule.__all__)``
-- ``__all__.append('a')``
-- ``__all__.remove('a')``
+that comprise its :ref:`interface <library-interface>` have type annotations
+that refer to types that are fully known. Private symbols are exempt.
 
 Type Completeness
 -----------------

docs/guides/writing_stubs.rst

@@ -5,7 +5,7 @@ Writing and Maintaining Stub Files
 **********************************
 
 Stub files are a means of providing type information for Python modules.
-For a full reference, refer to :ref:`stubs`.
+For a full reference, refer to :ref:`stub-files`.
 
 Maintaining stubs can be a little cumbersome because they are separated from the
 implementation. This page lists some tools that make writing and maintaining

docs/reference/index.rst

@@ -8,7 +8,6 @@ Type System Reference
 
  generics
  protocols
- stubs
  best_practices
  quality
  typing Module Documentation <https://docs.python.org/3/library/typing.html>