Crossreferences to standard library in mypy docs, part 5 #7689

hoefling · 2019-10-10T23:12:07Z

Added references to the following documents:

kinds_of_types.rst
metaclasses.rst
python2.rst
python36.rst
running_mypy.rst
stubs.rst
supported_python_features.rst
type_inference_and_annotations.rst

This is part of splitting up the changes in #7624 into more readable PRs.

Signed-off-by: Oleg Höfling <oleg.hoefling@gmail.com>

hoefling · 2019-10-10T23:16:43Z

docs/source/kinds_of_types.rst

@@ -415,7 +415,7 @@ Disabling strict optional checking
 Mypy also has an option to treat ``None`` as a valid value for every
 type (in case you know Java, it's useful to think of it as similar to
 the Java ``null``). In this mode ``None`` is also valid for primitive
-types such as ``int`` and ``float``, and ``Optional[...]`` types are
+types such as ``int`` and ``float``, and :py:data:`~typing.Optional` types are


Is it a similar case to this one?

Yes. (No need to link int, float since they are well-known.)

hoefling · 2019-10-10T23:17:32Z

docs/source/kinds_of_types.rst

@@ -600,10 +600,10 @@ The type of class objects
 <484#the-type-of-class-objects>`.)

 Sometimes you want to talk about class objects that inherit from a
-given class.  This can be spelled as ``Type[C]`` where ``C`` is a
+given class.  This can be spelled as :py:class:`Type[C] <typing.Type>` where ``C`` is a


Please advise whether the reference is useful here.

Pretty marginal, since this section explains the meaning of Type[]. But I think it's still fine to link to it.

hoefling · 2019-10-10T23:19:00Z

docs/source/kinds_of_types.rst

@@ -634,7 +634,7 @@ you pass it the right class object:
       # (Here we could write the user object to a database)
       return user

-How would we annotate this function?  Without ``Type[]`` the best we
+How would we annotate this function?  Without :py:class:`~typing.Type` the best we


Is it wise to remove the brackets here? TBH I didn't understand their meaning here.

It's fine. The meaning is similar to the use of () after a name (e.g. foo()) to emphasize that it's a function. (The latter usage goes back to the oldest UNIX manuals and/or K&R's original C book.) But it's not ambiguous in this context, so they can go.

hoefling · 2019-10-10T23:20:15Z

docs/source/metaclasses.rst

@@ -32,7 +32,7 @@ In Python 2, the syntax for defining a metaclass is different:
    class A(object):
        __metaclass__ = M

-Mypy also supports using :py:func:`six.with_metaclass`
+Mypy also supports using :py:func:`six.with_metaclass` and :py:func:`@six.add_metaclass <six.add_metaclass>`


I have decided to extend the text as the @six.add_metaclass decorator is used in the subsequent code example as well.

hoefling · 2019-10-10T23:21:08Z

docs/source/python2.rst

@@ -15,7 +15,7 @@ Run mypy in Python 2 mode by using the ``--py2`` option::
 To run your program, you must have the ``typing`` module in your
 Python 2 module search path. Use ``pip install typing`` to install the
 module. This also works for Python 3 versions prior to 3.5 that don't
-include ``typing`` in the standard library.
+include :py:mod:`typing` in the standard library.


Maybe not add any references in this document at all?

Hm, this one reference seems fine.

gvanrossum

1-2 nits need action.

gvanrossum · 2019-10-12T16:46:27Z

docs/source/kinds_of_types.rst

@@ -108,7 +108,7 @@ The ``Any`` type is discussed in more detail in section :ref:`dynamic-typing`.
 Tuple types
 ***********

-The type ``Tuple[T1, ..., Tn]`` represents a tuple with the item types ``T1``, ..., ``Tn``:
+The type ``Tuple[T1, ..., Tn]`` represents a :py:data:`~typing.Tuple` with the item types ``T1``, ..., ``Tn``:


I think this is wrong -- "tuple" here references the builtin tuple type, or the informal "tuple" concept, but making it reference typing.Tuple seems tautological.

Indeed - now it sounds like "the Tuple type represents itself", which is nonsensical. I guess my desire to reference the typing.Tuple type here and not touch Tuple[T1, ..., Tn] simultaneously played a bad joke on me. Will revert!

gvanrossum · 2019-10-12T16:48:45Z

docs/source/kinds_of_types.rst

@@ -415,7 +415,7 @@ Disabling strict optional checking
 Mypy also has an option to treat ``None`` as a valid value for every
 type (in case you know Java, it's useful to think of it as similar to
 the Java ``null``). In this mode ``None`` is also valid for primitive
-types such as ``int`` and ``float``, and ``Optional[...]`` types are
+types such as ``int`` and ``float``, and :py:data:`~typing.Optional` types are


Yes. (No need to link int, float since they are well-known.)

gvanrossum · 2019-10-12T16:50:53Z

docs/source/kinds_of_types.rst

@@ -600,10 +600,10 @@ The type of class objects
 <484#the-type-of-class-objects>`.)

 Sometimes you want to talk about class objects that inherit from a
-given class.  This can be spelled as ``Type[C]`` where ``C`` is a
+given class.  This can be spelled as :py:class:`Type[C] <typing.Type>` where ``C`` is a


Pretty marginal, since this section explains the meaning of Type[]. But I think it's still fine to link to it.

gvanrossum · 2019-10-12T16:52:40Z

docs/source/kinds_of_types.rst

@@ -634,7 +634,7 @@ you pass it the right class object:
       # (Here we could write the user object to a database)
       return user

-How would we annotate this function?  Without ``Type[]`` the best we
+How would we annotate this function?  Without :py:class:`~typing.Type` the best we


It's fine. The meaning is similar to the use of () after a name (e.g. foo()) to emphasize that it's a function. (The latter usage goes back to the oldest UNIX manuals and/or K&R's original C book.) But it's not ambiguous in this context, so they can go.

gvanrossum · 2019-10-12T16:54:20Z

docs/source/kinds_of_types.rst

   object that's a subtype of ``C``.  Its constructor must be
   compatible with the constructor of ``C``.  If ``C`` is a type
   variable, its upper bound must be a class object.

-For more details about ``Type[]`` see :pep:`PEP 484: The type of
+For more details about :py:class:`~typing.Type` see :pep:`PEP 484: The type of


This is kind of funny since there are now two references in the sentence, to different "sources of truth". I'll defer to your own sense of style in this case.

Indeed - I would rather revert to PEP 484 as the typing.Type docs are too brief.

gvanrossum · 2019-10-12T16:57:50Z

docs/source/metaclasses.rst


-Mypy has some special understanding of ``ABCMeta`` and ``EnumMeta``.
+Mypy has some special understanding of :py:class:`~abc.ABCMeta` and ``EnumMeta``.


Too bad there's no formal docs for EnumMeta, but I guess we can't do anything about it.

Yes, unfortunately! The only reference to EnumMeta I found in the stdlib docs is a brief mentioning in Enum Classes. No reference to link to in PEP 435 either.

gvanrossum · 2019-10-12T16:58:45Z

docs/source/python2.rst

@@ -15,7 +15,7 @@ Run mypy in Python 2 mode by using the ``--py2`` option::
 To run your program, you must have the ``typing`` module in your
 Python 2 module search path. Use ``pip install typing`` to install the
 module. This also works for Python 3 versions prior to 3.5 that don't
-include ``typing`` in the standard library.
+include :py:mod:`typing` in the standard library.


Hm, this one reference seems fine.

Signed-off-by: Oleg Höfling <oleg.hoefling@gmail.com>

revisited remaining documents except more_types.rst and protocols.rst

b16a607

Signed-off-by: Oleg Höfling <oleg.hoefling@gmail.com>

hoefling commented Oct 10, 2019

View reviewed changes

gvanrossum reviewed Oct 12, 2019

View reviewed changes

reverted unlucky refs

fe3a030

Signed-off-by: Oleg Höfling <oleg.hoefling@gmail.com>

gvanrossum approved these changes Oct 12, 2019

View reviewed changes

gvanrossum merged commit 0e41cce into python:master Oct 12, 2019

hoefling deleted the stdlib-crossref-5 branch October 13, 2019 07:26


		Mypy has some special understanding of ``ABCMeta`` and ``EnumMeta``.
		Mypy has some special understanding of :py:class:`~abc.ABCMeta` and ``EnumMeta``.

Uh oh!

Crossreferences to standard library in mypy docs, part 5 #7689

Crossreferences to standard library in mypy docs, part 5 #7689

Uh oh!

Conversation

hoefling commented Oct 10, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gvanrossum left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.