📝 Add docs about params as functions for mypy (fastapi#231)

tiangolo · web-flow · commit d24042137867 · 2019-05-15T22:01:23.000+04:00
diff --git a/docs/release-notes.md b/docs/release-notes.md
@@ -1,5 +1,7 @@
 ## Next release
 
+* Make default parameter utilities exported from `fastapi` be functions instead of classes (the new functions return instances of those classes). To be able to override the return types and fix `mypy` errors in FastAPI's users' code. Applies to `Path`, `Query`, `Header`, `Cookie`, `Body`, `Form`, `File`, `Depends`, and `Security`. PR [#226](https://github.com/tiangolo/fastapi/pull/226).
+
 * Re-enable `black` formatting checks for Python 3.7. PR [#229](https://github.com/tiangolo/fastapi/pull/229) by [@zamiramir](https://github.com/zamiramir).
 
 ## 0.21.0
diff --git a/docs/tutorial/body-schema.md b/docs/tutorial/body-schema.md
@@ -22,12 +22,13 @@ You can then use `Schema` with model attributes:
 
 `Schema` works the same way as `Query`, `Path` and `Body`, it has all the same parameters, etc.
 
-
-!!! info
+!!! note "Technical Details"
     Actually, `Query`, `Path` and others you'll see next are subclasses of a common `Param` which is itself a subclass of Pydantic's `Schema`.
 
     `Body` is also a subclass of `Schema` directly. And there are others you will see later that are subclasses of `Body`.
 
+    But remember that when you import `Query`, `Path` and others from `fastapi`, <a href="https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#recap" target="_blank">those are actually functions that return classes of the same name</a>.
+
 !!! tip
     Notice how each model's attribute with a type, default value and `Schema` has the same structure as a path operation function's parameter, with `Schema` instead of `Path`, `Query` and `Body`.
 
diff --git a/docs/tutorial/cookie-params.md b/docs/tutorial/cookie-params.md
@@ -18,9 +18,11 @@ The first value is the default value, you can pass all the extra validation or a
 {!./src/cookie_params/tutorial001.py!}
 ```
 
-!!! info
+!!! note "Technical Details"
     `Cookie` is a "sister" class of `Path` and `Query`. It also inherits from the same common `Param` class.
 
+    But remember that when you import `Query`, `Path`, `Cookie` and others from `fastapi`, <a href="https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#recap" target="_blank">those are actually functions that return classes of the same name</a>.
+
 !!! info
     To declare cookies, you need to use `Cookie`, because otherwise the parameters would be interpreted as query parameters.
 
diff --git a/docs/tutorial/header-params.md b/docs/tutorial/header-params.md
@@ -18,9 +18,11 @@ The first value is the default value, you can pass all the extra validation or a
 {!./src/header_params/tutorial001.py!}
 ```
 
-!!! info
+!!! note "Technical Details"
     `Header` is a "sister" class of `Path`, `Query` and `Cookie`. It also inherits from the same common `Param` class.
 
+    But remember that when you import `Query`, `Path`, `Header`, and others from `fastapi`, <a href="https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#recap" target="_blank">those are actually functions that return classes of the same name</a>.
+
 !!! info
     To declare headers, you need to use `Header`, because otherwise the parameters would be interpreted as query parameters.
 
diff --git a/docs/tutorial/path-params-numeric-validations.md b/docs/tutorial/path-params-numeric-validations.md
@@ -103,6 +103,17 @@ And you can also declare numeric validations:
 * `le`: `l`ess than or `e`qual
 
 !!! info
-    `Query`, `Path` and others you will see later are subclasses of a common `Param` class (that you don't need to use).
-    
-    And all of them share the same all these same parameters of additional validation and metadata you have seen.
+    `Query`, `Path` and others you will see later subclasses of a common `Param` class (that you don't need to use).
+
+    And all of them share the same all these same parameters of additional validation and metadata you have seen.
+
+!!! note "Technical Details"
+    When you import `Query`, `Path` and others from `fastapi`, they are actually functions.
+
+    That when called, return instances of classes of the same name.
+
+    So, you import `Query`, which is a function. And when you call it, it returns an instance of a class also named `Query`.
+
+    These functions are there (instead of just using the classes directly) so that your editor doesn't mark errors about their types.
+
+    That way you can use your normal editor and coding tools without having to add custom configurations to disregard those errors.
diff --git a/docs/tutorial/request-files.md b/docs/tutorial/request-files.md
@@ -19,6 +19,8 @@ Create file parameters the same way you would for `Body` or `Form`:
 !!! info
     `File` is a class that inherits directly from `Form`.
 
+    But remember that when you import `Query`, `Path`, `File` and others from `fastapi`, <a href="https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#recap" target="_blank">those are actually functions that return classes of the same name</a>.
+
 !!! info
     To declare File bodies, you need to use `File`, because otherwise the parameters would be interpreted as query parameters or body (JSON) parameters.
 
diff --git a/docs/tutorial/security/oauth2-scopes.md b/docs/tutorial/security/oauth2-scopes.md
@@ -108,6 +108,8 @@ In this case, it requires the scope `me` (it could require more than one scope).
 
     But by using `Security` instead of `Depends`, **FastAPI** will know that it can declare security scopes, use them internally, and document the API with OpenAPI.
 
+    But when you import `Query`, `Path`, `Depends`, `Security` and others from `fastapi`, <a href="https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#recap" target="_blank">those are actually functions that return classes of the same name</a>.
+
 ## Use `SecurityScopes`
 
 Now update the dependency `get_current_user`.
