From 34f509d8da1710039634bc16f5336570c4861bcd Mon Sep 17 00:00:00 2001 From: Steven Silvester Date: Thu, 12 Jan 2023 16:04:14 -0600 Subject: [PATCH] Add api docs (#1159) * add api docs * debug * more debug * try again * try again * try again * deps Co-authored-by: Carol Willing --- .github/workflows/python-tests.yml | 9 +++ docs/source/api/jupyter_server.auth.rst | 55 +++++++++++++++ docs/source/api/jupyter_server.base.rst | 31 +++++++++ docs/source/api/jupyter_server.extension.rst | 49 ++++++++++++++ docs/source/api/jupyter_server.files.rst | 19 ++++++ docs/source/api/jupyter_server.gateway.rst | 31 +++++++++ docs/source/api/jupyter_server.i18n.rst | 10 +++ .../source/api/jupyter_server.kernelspecs.rst | 19 ++++++ docs/source/api/jupyter_server.nbconvert.rst | 19 ++++++ docs/source/api/jupyter_server.prometheus.rst | 25 +++++++ docs/source/api/jupyter_server.rst | 67 +++++++++++++++++++ .../api/jupyter_server.services.api.rst | 19 ++++++ .../api/jupyter_server.services.config.rst | 25 +++++++ .../api/jupyter_server.services.contents.rst | 55 +++++++++++++++ .../api/jupyter_server.services.events.rst | 19 ++++++ ...ter_server.services.kernels.connection.rst | 31 +++++++++ .../api/jupyter_server.services.kernels.rst | 39 +++++++++++ .../jupyter_server.services.kernelspecs.rst | 19 ++++++ .../api/jupyter_server.services.nbconvert.rst | 19 ++++++ docs/source/api/jupyter_server.services.rst | 35 ++++++++++ .../api/jupyter_server.services.security.rst | 19 ++++++ .../api/jupyter_server.services.sessions.rst | 25 +++++++ docs/source/api/jupyter_server.view.rst | 19 ++++++ docs/source/api/modules.rst | 7 ++ docs/source/conf.py | 8 ++- docs/source/developers/index.rst | 1 + docs/source/operators/security.rst | 12 ++-- jupyter_server/auth/authorizer.py | 10 +-- jupyter_server/auth/identity.py | 6 +- jupyter_server/extension/application.py | 23 ++++--- jupyter_server/gateway/gateway_client.py | 8 +-- .../services/contents/checkpoints.py | 48 +++++++------ jupyter_server/services/contents/fileio.py | 4 +- .../services/contents/filemanager.py | 10 +-- jupyter_server/services/contents/manager.py | 24 +++---- .../services/sessions/sessionmanager.py | 2 +- jupyter_server/utils.py | 15 ++++- pyproject.toml | 4 +- 38 files changed, 762 insertions(+), 78 deletions(-) create mode 100644 docs/source/api/jupyter_server.auth.rst create mode 100644 docs/source/api/jupyter_server.base.rst create mode 100644 docs/source/api/jupyter_server.extension.rst create mode 100644 docs/source/api/jupyter_server.files.rst create mode 100644 docs/source/api/jupyter_server.gateway.rst create mode 100644 docs/source/api/jupyter_server.i18n.rst create mode 100644 docs/source/api/jupyter_server.kernelspecs.rst create mode 100644 docs/source/api/jupyter_server.nbconvert.rst create mode 100644 docs/source/api/jupyter_server.prometheus.rst create mode 100644 docs/source/api/jupyter_server.rst create mode 100644 docs/source/api/jupyter_server.services.api.rst create mode 100644 docs/source/api/jupyter_server.services.config.rst create mode 100644 docs/source/api/jupyter_server.services.contents.rst create mode 100644 docs/source/api/jupyter_server.services.events.rst create mode 100644 docs/source/api/jupyter_server.services.kernels.connection.rst create mode 100644 docs/source/api/jupyter_server.services.kernels.rst create mode 100644 docs/source/api/jupyter_server.services.kernelspecs.rst create mode 100644 docs/source/api/jupyter_server.services.nbconvert.rst create mode 100644 docs/source/api/jupyter_server.services.rst create mode 100644 docs/source/api/jupyter_server.services.security.rst create mode 100644 docs/source/api/jupyter_server.services.sessions.rst create mode 100644 docs/source/api/jupyter_server.view.rst create mode 100644 docs/source/api/modules.rst diff --git a/.github/workflows/python-tests.yml b/.github/workflows/python-tests.yml index b183c9e1e4..bac6730f8b 100644 --- a/.github/workflows/python-tests.yml +++ b/.github/workflows/python-tests.yml @@ -61,6 +61,15 @@ jobs: run: | sudo apt-get update sudo apt-get install enchant-2 # for spell checking + - name: Build API docs + run: | + hatch run docs:api + # If this fails run `hatch run docs:api` locally + # and commit. + git status --porcelain + git status -s | grep "A" && exit 1 + git status -s | grep "M" && exit 1 + echo "API docs done" - run: hatch run docs:build test_lint: diff --git a/docs/source/api/jupyter_server.auth.rst b/docs/source/api/jupyter_server.auth.rst new file mode 100644 index 0000000000..66c364b44c --- /dev/null +++ b/docs/source/api/jupyter_server.auth.rst @@ -0,0 +1,55 @@ +jupyter\_server.auth package +============================ + +Submodules +---------- + + +.. automodule:: jupyter_server.auth.authorizer + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.auth.decorator + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.auth.identity + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.auth.login + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.auth.logout + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.auth.security + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.auth.utils + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_server.auth + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/jupyter_server.base.rst b/docs/source/api/jupyter_server.base.rst new file mode 100644 index 0000000000..42aa6211ff --- /dev/null +++ b/docs/source/api/jupyter_server.base.rst @@ -0,0 +1,31 @@ +jupyter\_server.base package +============================ + +Submodules +---------- + + +.. automodule:: jupyter_server.base.handlers + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.base.websocket + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.base.zmqhandlers + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_server.base + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/jupyter_server.extension.rst b/docs/source/api/jupyter_server.extension.rst new file mode 100644 index 0000000000..4610c696e6 --- /dev/null +++ b/docs/source/api/jupyter_server.extension.rst @@ -0,0 +1,49 @@ +jupyter\_server.extension package +================================= + +Submodules +---------- + + +.. automodule:: jupyter_server.extension.application + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.extension.config + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.extension.handler + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.extension.manager + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.extension.serverextension + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.extension.utils + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_server.extension + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/jupyter_server.files.rst b/docs/source/api/jupyter_server.files.rst new file mode 100644 index 0000000000..892865814a --- /dev/null +++ b/docs/source/api/jupyter_server.files.rst @@ -0,0 +1,19 @@ +jupyter\_server.files package +============================= + +Submodules +---------- + + +.. automodule:: jupyter_server.files.handlers + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_server.files + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/jupyter_server.gateway.rst b/docs/source/api/jupyter_server.gateway.rst new file mode 100644 index 0000000000..57f2c6235e --- /dev/null +++ b/docs/source/api/jupyter_server.gateway.rst @@ -0,0 +1,31 @@ +jupyter\_server.gateway package +=============================== + +Submodules +---------- + + +.. automodule:: jupyter_server.gateway.gateway_client + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.gateway.handlers + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.gateway.managers + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_server.gateway + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/jupyter_server.i18n.rst b/docs/source/api/jupyter_server.i18n.rst new file mode 100644 index 0000000000..ada5d341bb --- /dev/null +++ b/docs/source/api/jupyter_server.i18n.rst @@ -0,0 +1,10 @@ +jupyter\_server.i18n package +============================ + +Module contents +--------------- + +.. automodule:: jupyter_server.i18n + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/jupyter_server.kernelspecs.rst b/docs/source/api/jupyter_server.kernelspecs.rst new file mode 100644 index 0000000000..0c36baf16e --- /dev/null +++ b/docs/source/api/jupyter_server.kernelspecs.rst @@ -0,0 +1,19 @@ +jupyter\_server.kernelspecs package +=================================== + +Submodules +---------- + + +.. automodule:: jupyter_server.kernelspecs.handlers + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_server.kernelspecs + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/jupyter_server.nbconvert.rst b/docs/source/api/jupyter_server.nbconvert.rst new file mode 100644 index 0000000000..52d9dc00ad --- /dev/null +++ b/docs/source/api/jupyter_server.nbconvert.rst @@ -0,0 +1,19 @@ +jupyter\_server.nbconvert package +================================= + +Submodules +---------- + + +.. automodule:: jupyter_server.nbconvert.handlers + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_server.nbconvert + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/jupyter_server.prometheus.rst b/docs/source/api/jupyter_server.prometheus.rst new file mode 100644 index 0000000000..91a61ed686 --- /dev/null +++ b/docs/source/api/jupyter_server.prometheus.rst @@ -0,0 +1,25 @@ +jupyter\_server.prometheus package +================================== + +Submodules +---------- + + +.. automodule:: jupyter_server.prometheus.log_functions + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.prometheus.metrics + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_server.prometheus + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/jupyter_server.rst b/docs/source/api/jupyter_server.rst new file mode 100644 index 0000000000..6402594325 --- /dev/null +++ b/docs/source/api/jupyter_server.rst @@ -0,0 +1,67 @@ +jupyter\_server package +======================= + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + jupyter_server.auth + jupyter_server.base + jupyter_server.extension + jupyter_server.files + jupyter_server.gateway + jupyter_server.i18n + jupyter_server.kernelspecs + jupyter_server.nbconvert + jupyter_server.prometheus + jupyter_server.services + jupyter_server.view + +Submodules +---------- + + +.. automodule:: jupyter_server.config_manager + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.log + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.serverapp + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.traittypes + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.transutils + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.utils + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_server + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/jupyter_server.services.api.rst b/docs/source/api/jupyter_server.services.api.rst new file mode 100644 index 0000000000..e7389bc02d --- /dev/null +++ b/docs/source/api/jupyter_server.services.api.rst @@ -0,0 +1,19 @@ +jupyter\_server.services.api package +==================================== + +Submodules +---------- + + +.. automodule:: jupyter_server.services.api.handlers + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_server.services.api + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/jupyter_server.services.config.rst b/docs/source/api/jupyter_server.services.config.rst new file mode 100644 index 0000000000..7f1c1d1e23 --- /dev/null +++ b/docs/source/api/jupyter_server.services.config.rst @@ -0,0 +1,25 @@ +jupyter\_server.services.config package +======================================= + +Submodules +---------- + + +.. automodule:: jupyter_server.services.config.handlers + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.services.config.manager + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_server.services.config + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/jupyter_server.services.contents.rst b/docs/source/api/jupyter_server.services.contents.rst new file mode 100644 index 0000000000..bf33989ea1 --- /dev/null +++ b/docs/source/api/jupyter_server.services.contents.rst @@ -0,0 +1,55 @@ +jupyter\_server.services.contents package +========================================= + +Submodules +---------- + + +.. automodule:: jupyter_server.services.contents.checkpoints + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.services.contents.filecheckpoints + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.services.contents.fileio + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.services.contents.filemanager + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.services.contents.handlers + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.services.contents.largefilemanager + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.services.contents.manager + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_server.services.contents + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/jupyter_server.services.events.rst b/docs/source/api/jupyter_server.services.events.rst new file mode 100644 index 0000000000..eebb056ac6 --- /dev/null +++ b/docs/source/api/jupyter_server.services.events.rst @@ -0,0 +1,19 @@ +jupyter\_server.services.events package +======================================= + +Submodules +---------- + + +.. automodule:: jupyter_server.services.events.handlers + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_server.services.events + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/jupyter_server.services.kernels.connection.rst b/docs/source/api/jupyter_server.services.kernels.connection.rst new file mode 100644 index 0000000000..076f81c46b --- /dev/null +++ b/docs/source/api/jupyter_server.services.kernels.connection.rst @@ -0,0 +1,31 @@ +jupyter\_server.services.kernels.connection package +=================================================== + +Submodules +---------- + + +.. automodule:: jupyter_server.services.kernels.connection.abc + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.services.kernels.connection.base + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.services.kernels.connection.channels + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_server.services.kernels.connection + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/jupyter_server.services.kernels.rst b/docs/source/api/jupyter_server.services.kernels.rst new file mode 100644 index 0000000000..865db764ce --- /dev/null +++ b/docs/source/api/jupyter_server.services.kernels.rst @@ -0,0 +1,39 @@ +jupyter\_server.services.kernels package +======================================== + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + jupyter_server.services.kernels.connection + +Submodules +---------- + + +.. automodule:: jupyter_server.services.kernels.handlers + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.services.kernels.kernelmanager + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.services.kernels.websocket + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_server.services.kernels + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/jupyter_server.services.kernelspecs.rst b/docs/source/api/jupyter_server.services.kernelspecs.rst new file mode 100644 index 0000000000..3f210d0f55 --- /dev/null +++ b/docs/source/api/jupyter_server.services.kernelspecs.rst @@ -0,0 +1,19 @@ +jupyter\_server.services.kernelspecs package +============================================ + +Submodules +---------- + + +.. automodule:: jupyter_server.services.kernelspecs.handlers + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_server.services.kernelspecs + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/jupyter_server.services.nbconvert.rst b/docs/source/api/jupyter_server.services.nbconvert.rst new file mode 100644 index 0000000000..cf5f0c037d --- /dev/null +++ b/docs/source/api/jupyter_server.services.nbconvert.rst @@ -0,0 +1,19 @@ +jupyter\_server.services.nbconvert package +========================================== + +Submodules +---------- + + +.. automodule:: jupyter_server.services.nbconvert.handlers + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_server.services.nbconvert + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/jupyter_server.services.rst b/docs/source/api/jupyter_server.services.rst new file mode 100644 index 0000000000..6f221e7357 --- /dev/null +++ b/docs/source/api/jupyter_server.services.rst @@ -0,0 +1,35 @@ +jupyter\_server.services package +================================ + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + jupyter_server.services.api + jupyter_server.services.config + jupyter_server.services.contents + jupyter_server.services.events + jupyter_server.services.kernels + jupyter_server.services.kernelspecs + jupyter_server.services.nbconvert + jupyter_server.services.security + jupyter_server.services.sessions + +Submodules +---------- + + +.. automodule:: jupyter_server.services.shutdown + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_server.services + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/jupyter_server.services.security.rst b/docs/source/api/jupyter_server.services.security.rst new file mode 100644 index 0000000000..7d7b2a975c --- /dev/null +++ b/docs/source/api/jupyter_server.services.security.rst @@ -0,0 +1,19 @@ +jupyter\_server.services.security package +========================================= + +Submodules +---------- + + +.. automodule:: jupyter_server.services.security.handlers + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_server.services.security + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/jupyter_server.services.sessions.rst b/docs/source/api/jupyter_server.services.sessions.rst new file mode 100644 index 0000000000..292de65c34 --- /dev/null +++ b/docs/source/api/jupyter_server.services.sessions.rst @@ -0,0 +1,25 @@ +jupyter\_server.services.sessions package +========================================= + +Submodules +---------- + + +.. automodule:: jupyter_server.services.sessions.handlers + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_server.services.sessions.sessionmanager + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_server.services.sessions + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/jupyter_server.view.rst b/docs/source/api/jupyter_server.view.rst new file mode 100644 index 0000000000..f83aff120e --- /dev/null +++ b/docs/source/api/jupyter_server.view.rst @@ -0,0 +1,19 @@ +jupyter\_server.view package +============================ + +Submodules +---------- + + +.. automodule:: jupyter_server.view.handlers + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_server.view + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/modules.rst b/docs/source/api/modules.rst new file mode 100644 index 0000000000..3237ddf087 --- /dev/null +++ b/docs/source/api/modules.rst @@ -0,0 +1,7 @@ +jupyter_server +============== + +.. toctree:: + :maxdepth: 4 + + jupyter_server diff --git a/docs/source/conf.py b/docs/source/conf.py index baff0ac994..77f29e7968 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -40,6 +40,7 @@ "sphinxcontrib_github_alt", "sphinxcontrib.openapi", "sphinxemoji.sphinxemoji", + "sphinx_autodoc_typehints", ] try: @@ -326,10 +327,11 @@ intersphinx_mapping = { "python": ("https://docs.python.org/", None), "ipython": ("https://ipython.readthedocs.io/en/stable/", None), - "nbconvert": ("https://nbconvert.readthedocs.io/en/latest/", None), - "nbformat": ("https://nbformat.readthedocs.io/en/latest/", None), - "jupyter": ("https://jupyter.readthedocs.io/en/latest/", None), + "nbconvert": ("https://nbconvert.readthedocs.io/en/stable/", None), + "nbformat": ("https://nbformat.readthedocs.io/en/stable/", None), + "jupyter_core": ("https://jupyter_core.readthedocs.io/en/stable/", None), "tornado": ("https://www.tornadoweb.org/en/stable/", None), + "traitlets": ("https://traitlets.readthedocs.io/en/stable/", None), } spelling_lang = "en_US" diff --git a/docs/source/developers/index.rst b/docs/source/developers/index.rst index 10ab7e1d8b..fb40f24797 100644 --- a/docs/source/developers/index.rst +++ b/docs/source/developers/index.rst @@ -15,3 +15,4 @@ These pages target people writing Jupyter Web applications and server extensions savehooks contents websocket-protocols + API Docs <../api/modules> diff --git a/docs/source/operators/security.rst b/docs/source/operators/security.rst index 0cba812ac5..5f1a861527 100644 --- a/docs/source/operators/security.rst +++ b/docs/source/operators/security.rst @@ -81,10 +81,10 @@ Authentication and Authorization There are two steps to deciding whether to allow a given request to be happen. The first step is "Authentication" (identifying who is making the request). -This is handled by the :class:`.IdentityProvider`. +This is handled by the :class:`jupyter_server.auth.IdentityProvider`. Whether a given user is allowed to take a specific action is called "Authorization", -and is handled separately, by an :class:`.Authorizer`. +and is handled separately, by an :class:`~jupyter_server.auth.Authorizer`. These two classes may work together, as the information returned by the IdentityProvider is given to the Authorizer when it makes its decisions. @@ -96,7 +96,7 @@ as all requests requiring _authorization_ must first complete _authentication_. Identity Providers ****************** -The :class:`.IdentityProvider` class is responsible for the "authentication" step, +The :class:`jupyter_server.auth.IdentityProvider` class is responsible for the "authentication" step, identifying the user making the request, and constructing information about them. @@ -107,9 +107,9 @@ It principally implements two methods. .. automethod:: get_user .. automethod:: identity_model -The first is :meth:`.IdentityProvider.get_user`. +The first is :meth:`jupyter_server.auth.IdentityProvider.get_user`. This method is given a RequestHandler, and is responsible for deciding whether there is an authenticated user making the request. -If the request is authenticated, it should return a :class:`.jupyter_server.auth.User` object representing the authenticated user. +If the request is authenticated, it should return a :class:`jupyter_server.auth.User` object representing the authenticated user. It should return None if the request is not authenticated. The default implementation accepts token or password authentication. @@ -125,7 +125,7 @@ The User object will be a Python :py:class:`dataclasses.dataclass`, `jupyter_ser A custom IdentityProvider _may_ return a custom subclass. -The next method an identity provider has is :meth:`~.IdentityProvider.identity_model`. +The next method an identity provider has is :meth:`~jupyter_server.auth.IdentityProvider.identity_model`. `identity_model(user)` is responsible for transforming the user object returned from `.get_user()` into a standard identity model dictionary, for use in the `/api/me` endpoint. diff --git a/jupyter_server/auth/authorizer.py b/jupyter_server/auth/authorizer.py index b1d95eeee4..f22dbe5463 100644 --- a/jupyter_server/auth/authorizer.py +++ b/jupyter_server/auth/authorizer.py @@ -26,10 +26,10 @@ class Authorizer(LoggingConfigurable): All authorizers used in Jupyter Server should inherit from this base class and, at the very minimum, - implement an `is_authorized` method with the + implement an ``is_authorized`` method with the same signature as in this base class. - The `is_authorized` method is called by the `@authorized` decorator + The ``is_authorized`` method is called by the ``@authorized`` decorator in JupyterHandler. If it returns True, the incoming request to the server is accepted; if it returns False, the server returns a 403 (Forbidden) error code. @@ -45,14 +45,14 @@ class Authorizer(LoggingConfigurable): def is_authorized( self, handler: JupyterHandler, user: User, action: str, resource: str ) -> bool: - """A method to determine if `user` is authorized to perform `action` - (read, write, or execute) on the `resource` type. + """A method to determine if ``user`` is authorized to perform ``action`` + (read, write, or execute) on the ``resource`` type. Parameters ---------- user : jupyter_server.auth.User An object representing the authenticated user, - as returned by :meth:`.IdentityProvider.get_user`. + as returned by :meth:`jupyter_server.auth.IdentityProvider.get_user`. action : str the category of action for the current request: read, write, or execute. diff --git a/jupyter_server/auth/identity.py b/jupyter_server/auth/identity.py index be5ead70d5..84fadf570d 100644 --- a/jupyter_server/auth/identity.py +++ b/jupyter_server/auth/identity.py @@ -118,9 +118,9 @@ class IdentityProvider(LoggingConfigurable): Two principle methods: - - :meth:`~.IdentityProvider.get_user` returns a :class:`~.User` object + - :meth:`~jupyter_server.auth.IdentityProvider.get_user` returns a :class:`~.User` object for successful authentication, or None for no-identity-found. - - :meth:`~.IdentityProvider.identity_model` turns a :class:`~.User` into a JSONable dict. + - :meth:`~jupyter_server.auth.IdentityProvider.identity_model` turns a :class:`~jupyter_server.auth.User` into a JSONable dict. The default is to use :py:meth:`dataclasses.asdict`, and usually shouldn't need override. @@ -217,7 +217,7 @@ def _token_default(self): def get_user(self, handler: JupyterHandler) -> User | None | Awaitable[User | None]: """Get the authenticated user for a request - Must return a :class:`.jupyter_server.auth.User`, + Must return a :class:`jupyter_server.auth.User`, though it may be a subclass. Return None if the request is not authenticated. diff --git a/jupyter_server/extension/application.py b/jupyter_server/extension/application.py index 2f9340bc87..4e895996b1 100644 --- a/jupyter_server/extension/application.py +++ b/jupyter_server/extension/application.py @@ -124,12 +124,14 @@ class ExtensionApp(JupyterApp): """Base class for configurable Jupyter Server Extension Applications. ExtensionApp subclasses can be initialized two ways: - 1. Extension is listed as a jpserver_extension, and ServerApp calls - its load_jupyter_server_extension classmethod. This is the - classic way of loading a server extension. - 2. Extension is launched directly by calling its `launch_instance` - class method. This method can be set as a entry_point in - the extensions setup.py + + - Extension is listed as a jpserver_extension, and ServerApp calls + its load_jupyter_server_extension classmethod. This is the + classic way of loading a server extension. + + - Extension is launched directly by calling its `launch_instance` + class method. This method can be set as a entry_point in + the extensions setup.py. """ # Subclasses should override this trait. Tells the server if @@ -409,11 +411,10 @@ def initialize(self): corresponding server app and webapp should already be initialized by this step. - 1) Appends Handlers to the ServerApp, - 2) Passes config and settings from ExtensionApp - to the Tornado web application - 3) Points Tornado Webapp to templates and - static assets. + - Appends Handlers to the ServerApp, + - Passes config and settings from ExtensionApp + to the Tornado web application + - Points Tornado Webapp to templates and static assets. """ if not self.serverapp: msg = ( diff --git a/jupyter_server/gateway/gateway_client.py b/jupyter_server/gateway/gateway_client.py index 47b68dc065..4de7055e60 100644 --- a/jupyter_server/gateway/gateway_client.py +++ b/jupyter_server/gateway/gateway_client.py @@ -69,10 +69,10 @@ def get_token( class GatewayClient(SingletonConfigurable): - """This class manages the configuration. It's its own singleton class so that we - can share these values across all objects. It also contains some helper methods - to build request arguments out of the various config options. - + """This class manages the configuration. It's its own singleton class so + that we can share these values across all objects. It also contains some + helper methods to build request arguments out of the various config + options. """ url = Unicode( diff --git a/jupyter_server/services/contents/checkpoints.py b/jupyter_server/services/contents/checkpoints.py index 5f68b5d693..e251f7b232 100644 --- a/jupyter_server/services/contents/checkpoints.py +++ b/jupyter_server/services/contents/checkpoints.py @@ -119,23 +119,25 @@ def create_notebook_checkpoint(self, nb, path): def get_file_checkpoint(self, checkpoint_id, path): """Get the content of a checkpoint for a non-notebook file. - Returns a dict of the form: - { - 'type': 'file', - 'content': , - 'format': {'text','base64'}, - } + Returns a dict of the form:: + + { + 'type': 'file', + 'content': , + 'format': {'text','base64'}, + } """ raise NotImplementedError def get_notebook_checkpoint(self, checkpoint_id, path): """Get the content of a checkpoint for a notebook. - Returns a dict of the form: - { - 'type': 'notebook', - 'content': , - } + Returns a dict of the form:: + + { + 'type': 'notebook', + 'content': , + } """ raise NotImplementedError @@ -229,22 +231,24 @@ async def create_notebook_checkpoint(self, nb, path): async def get_file_checkpoint(self, checkpoint_id, path): """Get the content of a checkpoint for a non-notebook file. - Returns a dict of the form: - { - 'type': 'file', - 'content': , - 'format': {'text','base64'}, - } + Returns a dict of the form:: + + { + 'type': 'file', + 'content': , + 'format': {'text','base64'}, + } """ raise NotImplementedError async def get_notebook_checkpoint(self, checkpoint_id, path): """Get the content of a checkpoint for a notebook. - Returns a dict of the form: - { - 'type': 'notebook', - 'content': , - } + Returns a dict of the form:: + + { + 'type': 'notebook', + 'content': , + } """ raise NotImplementedError diff --git a/jupyter_server/services/contents/fileio.py b/jupyter_server/services/contents/fileio.py index b4f05c9bea..f4a799671f 100644 --- a/jupyter_server/services/contents/fileio.py +++ b/jupyter_server/services/contents/fileio.py @@ -241,12 +241,12 @@ def _get_os_path(self, path): Parameters ---------- - path : string + path : str The relative API path to the named file. Returns ------- - path : string + path : str Native, absolute OS path to for a file. Raises diff --git a/jupyter_server/services/contents/filemanager.py b/jupyter_server/services/contents/filemanager.py index de0117a558..af6cc43310 100644 --- a/jupyter_server/services/contents/filemanager.py +++ b/jupyter_server/services/contents/filemanager.py @@ -121,7 +121,7 @@ def is_hidden(self, path): Parameters ---------- - path : string + path : str The path to check. This is an API path (`/` separated, relative to root_dir). @@ -139,7 +139,7 @@ def is_writable(self, path): Parameters ---------- - path : string + path : str The path to check. This is an API path (`/` separated, relative to root_dir). @@ -163,7 +163,7 @@ def file_exists(self, path): Parameters ---------- - path : string + path : str The relative path to the file (with '/' as separator) Returns @@ -182,7 +182,7 @@ def dir_exists(self, path): Parameters ---------- - path : string + path : str The path to check. This is an API path (`/` separated, relative to root_dir). @@ -202,7 +202,7 @@ def exists(self, path): Parameters ---------- - path : string + path : str The API path to the file (with '/' as separator) Returns diff --git a/jupyter_server/services/contents/manager.py b/jupyter_server/services/contents/manager.py index 158326d879..110bd180ef 100644 --- a/jupyter_server/services/contents/manager.py +++ b/jupyter_server/services/contents/manager.py @@ -370,7 +370,7 @@ def dir_exists(self, path): Parameters ---------- - path : string + path : str The path to check Returns @@ -385,7 +385,7 @@ def is_hidden(self, path): Parameters ---------- - path : string + path : str The path to check. This is an API path (`/` separated, relative to root dir). @@ -406,7 +406,7 @@ def file_exists(self, path=""): Parameters ---------- - path : string + path : str The API path of a file to check for. Returns @@ -423,7 +423,7 @@ def exists(self, path): Parameters ---------- - path : string + path : str The API path of a file or directory to check for. Returns @@ -680,7 +680,7 @@ def trust_notebook(self, path): Parameters ---------- - path : string + path : str The path of a notebook """ model = self.get(path) @@ -698,7 +698,7 @@ def check_and_sign(self, nb, path=""): ---------- nb : dict The notebook dict - path : string + path : str The notebook's path (for logging) """ if self.notary.check_cells(nb): @@ -715,7 +715,7 @@ def mark_trusted_cells(self, nb, path=""): ---------- nb : dict The notebook object (in current nbformat) - path : string + path : str The notebook's path (for logging) """ trusted = self.notary.check_signature(nb) @@ -775,7 +775,7 @@ async def dir_exists(self, path): Parameters ---------- - path : string + path : str The path to check Returns @@ -790,7 +790,7 @@ async def is_hidden(self, path): Parameters ---------- - path : string + path : str The path to check. This is an API path (`/` separated, relative to root dir). @@ -811,7 +811,7 @@ async def file_exists(self, path=""): Parameters ---------- - path : string + path : str The API path of a file to check for. Returns @@ -828,7 +828,7 @@ async def exists(self, path): Parameters ---------- - path : string + path : str The API path of a file or directory to check for. Returns @@ -1049,7 +1049,7 @@ async def trust_notebook(self, path): Parameters ---------- - path : string + path : str The path of a notebook """ model = await self.get(path) diff --git a/jupyter_server/services/sessions/sessionmanager.py b/jupyter_server/services/sessions/sessionmanager.py index 7087131172..09d438af84 100644 --- a/jupyter_server/services/sessions/sessionmanager.py +++ b/jupyter_server/services/sessions/sessionmanager.py @@ -388,7 +388,7 @@ async def get_session(self, **kwargs): Parameters ---------- - **kwargs : keyword argument + **kwargs : dict must be given one of the keywords and values from the session database (i.e. session_id, path, name, type, kernel_id) diff --git a/jupyter_server/utils.py b/jupyter_server/utils.py index e9e9c63780..6e3297b6c1 100644 --- a/jupyter_server/utils.py +++ b/jupyter_server/utils.py @@ -100,8 +100,10 @@ def samefile_simple(path, other_path): Parameters ---------- - path : String representing a path to a file - other_path : String representing a path to another file + path : str + representing a path to a file + other_path : str + representing a path to another file Returns ------- @@ -326,11 +328,16 @@ def filefind(filename, path_dirs=None): the full, absolute path of the first occurence of the file. If no set of path dirs is given, the filename is tested as is, after running through :func:`expandvars` and :func:`expanduser`. Thus a simple call:: + filefind('myfile.txt') + will find the file in the current working dir, but:: + filefind('~/myfile.txt') + Will find the file in the users home directory. This function does not automatically try any paths, such as the cwd or the user's home directory. + Parameters ---------- filename : str @@ -341,6 +348,7 @@ def filefind(filename, path_dirs=None): put into a sequence and the searched. If a sequence, walk through each element and join with ``filename``, calling :func:`expandvars` and :func:`expanduser` before testing for existence. + Returns ------- Raises :exc:`IOError` or returns absolute path to file. @@ -370,6 +378,7 @@ def filefind(filename, path_dirs=None): def expand_path(s): """Expand $VARS and ~names in a string, like a shell + :Examples: In [2]: os.environ['FOO']='test' In [3]: expand_path('variable FOO is $FOO') @@ -394,7 +403,7 @@ def import_item(name): executing the code ``from foo import bar``. Parameters ---------- - name : string + name : str The fully qualified name of the module/package being imported. Returns ------- diff --git a/pyproject.toml b/pyproject.toml index a01a52004d..0bbb1746b6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -81,6 +81,7 @@ docs = [ "sphinxcontrib-openapi", "sphinxcontrib_github_alt", "sphinxcontrib-spelling", + "sphinx-autodoc-typehints", "sphinxemoji", "tornado", ] @@ -92,6 +93,7 @@ jupyter-server = "jupyter_server.serverapp:main" features = ["docs"] [tool.hatch.envs.docs.scripts] build = "make -C docs html SPHINXOPTS='-W'" +api = "sphinx-apidoc -o docs/source/api -f -E jupyter_server */terminal jupyter_server/pytest_plugin.py" [tool.hatch.envs.test] features = ["test"] @@ -118,7 +120,7 @@ detached = true dependencies = [ "black[jupyter]==22.12.0", "mdformat>0.7", - "ruff==0.0.194", + "ruff==0.0.206", ] [tool.hatch.envs.lint.scripts] style = [