Backport PR #7244 on branch 7.0.x (Add documentation for updating notebook imports) (#7245)

meeseeksmachine · jtpio · pre-commit-ci[bot] · web-flow · commit 99db9423e34e · 2024-02-08T17:12:31.000+01:00
* Backport PR #7244: Add documentation for updating `notebook` imports * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --------- Co-authored-by: Jeremy Tuloup <jeremy.tuloup@gmail.com> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
diff --git a/docs/source/configuring/config_overview.md b/docs/source/configuring/config_overview.md
@@ -52,6 +52,12 @@ front-end Notebook client (i.e. the familiar notebook interface).
 > - Related: [Configuring a language kernel](https://ipython.readthedocs.io/en/latest/install/kernel_install.html)
 >   to run in the Jupyter Server enables your server to run other languages, like R or Julia.
 
+```{warning}
+Jupyter Notebook 7 is now based on Jupyter Server. This may break some previous `notebook` imports you may have been using, such as `notebook.auth` or `notebook.notebookapp`.
+
+Check out the [migration guide](../migrating/server-imports.md) to learn more on how to update these server imports.
+```
+
 (configure-nbextensions)=
 
 ## Notebook extensions
diff --git a/docs/source/migrate_to_notebook7.md b/docs/source/migrate_to_notebook7.md
@@ -73,6 +73,7 @@ notebook_7_features.md
 
 migrating/frontend-extensions.md
 migrating/server-extensions.md
+migrating/server-imports.md
 migrating/custom-themes.md
 migrating/multiple-interfaces.md
 ```
diff --git a/docs/source/migrating/server-imports.md b/docs/source/migrating/server-imports.md
@@ -0,0 +1,37 @@
+# Server Imports in Notebook 7
+
+Notebook 7 is now based on Jupyter Server, which lets users run multiple Jupyter frontends (e.g. Notebook, JupyterLab, NBClassic, etc.) on the same server.
+
+Prior to Notebook 7, the Classic Notebook server included the server modules in the `notebook` package. This means it was possible to import the server modules from the `notebook` package, for example:
+
+```python
+from notebook.auth import passwd
+
+passwd("foo")
+```
+
+Or:
+
+```python
+from notebook import notebookapp
+
+notebookapp.list_running_servers()
+```
+
+In Notebook 7, these server modules are now exposed by the `jupyter_server` package. The code snippets above should be updated to:
+
+```python
+from jupyter_server.auth import passwd
+
+passwd("foo")
+```
+
+And:
+
+```python
+from jupyter_server import serverapp
+
+serverapp.list_running_servers()
+```
+
+These are just examples, so you may have to adjust your use of `notebook` imports based on the specific server modules you were using.
