Repository: python/mypy
Pull request: Add docs for --local-partial-types option
resolves #8046, document the `--local-partial-types` command line option

Problem statement:
dmypy and mypy behave differently with same settings
Consider this example:

```
class Config:
    url = None

    def __init__(self) -> None:
        self.url = 'xxx'
```

`mypy` says there are no errors, but `dmypy` with the same settings finds one:

```
$ mypy example.py
Success: no issues found in 1 source file

$ dmypy run -- --follow-imports=skip example.py
Daemon started
example.py:3: error: Need type annotation for 'url'
Found 1 error in 1 file (checked 1 source file)

```

my package versions:

```

$ python --version
Python 3.6.5 :: Anaconda, Inc.
$ mypy --version
mypy 0.750
```

Hints from issue discussion:
Yeah, this is a known issue (but it might be undocumented). You can use `--local-partial-types` to get the `dmypy` semantics when using `mypy`.

At some point we'll likely make `--local-partial-types` enabled by default.
Thanks! Can you provide any link to docs regarding  `local-partial-types` at least for regular mypy? I can't seem to find one on the docs webpage.
It looks like we've forgotten to document it.

Commit message: automatically update author info

Patch to review:
diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst
index 0cfcbe98cb86..969d7218dbee 100644
--- a/docs/source/command_line.rst
+++ b/docs/source/command_line.rst
@@ -482,6 +482,23 @@ of the above sections.
            # 'items' now has type List[List[str]]
            ...
 
+.. option:: --local-partial-types
+
+    By default, mypy won't check partial types spanning module top level or class top level.
+    This flag changes the behavior to only allow partial types at local level. For example:
+
+    .. code-block:: python
+
+        from typing import Optional
+
+        a = None  # error
+        b = None  # type: Optional[str]
+
+        class Foo:
+            bar = None  # error
+            boo = None  # type: Optional[int]
+
+
 .. option:: --no-implicit-reexport
 
     By default, imported values to a module are treated as exported and mypy allows


Code review comments:
diff_hunk: @@ -482,6 +482,23 @@ of the above sections.
            # 'items' now has type List[List[str]]
            ...
 
+.. option:: --local-partial-types
+
+    By default, mypy won't check partial types spanning module top level or class top level.
+    This flag changes the behavior to only allow partial types at local level. For example:
path: docs/source/command_line.rst
text: @user1:
We don't mention partial types anywhere else in the documentation, so they are essentially a low-level implementation concept. It would be better if the explanation would explain what the option does without referring to the partial types concept.

Also mention that this is always implicitly enabled in the mypy daemon and will become enabled by default in a future mypy release.

@author:
Good catch, what do you suggest as an alternative for partial types that is more user-friendly to non-devs?

@author:
My current thoughts are to keep the name 'partial types' unchanged in the docs, in correspondence with the option name, and provide some description for partial types, maybe like
`Types such as List[?] where type arguments are unknown, or None type without explicit Option annotation` so the readers can connect the name with some concrete examples