:memo: Add docs about params as functions for mypy (#231)

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 54032d902fcb84c95f84e2f2bae56f28799ec5c6..257c945577722d39ed525563f8c7f63ffd1b6dde 100644 (file)
--- 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
index 878c2217decefbab9f2e22bfb9f664b0b6bd4bf2..45ea5d93d4022d77e061652b1603fd06d63cfc0a 100644 (file)
--- 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
index 1fb5b16c23394ee27bbaa518e15f70f935a83618..62d93ce6ce28f5fabdfc81121bf89970f411fbfb 100644 (file)
--- 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
index f2da422254f308cccf51419e2df4e817851a318e..503d612ed77331b5a3c69d35bb6ebe065174cc39 100644 (file)
--- 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
index 4ea24382eeb4a712221d7fb7cac5f2429f284284..80ace2624ce71d74cf32fa3e4ea63ae6478e459d 100644 (file)
--- 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.
\ No newline at end of file
+    `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
index 10dd16e32fb123474946ae7a1910f778c1f1cb08..e95f9b97aa5cd8d6623b522f5648d4eb56fa6682 100644 (file)
--- 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
index e290d5e8ed396fdc728e9fc55132c67b279fb2ce..ef4f6798ec469d21a21c5923418faca446cba30e 100644 (file)
--- 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`.