Canvas
======

.. automodule:: jupyterhub_oauthenticator_authz_helpers.canvas
   :members:

   .. note::

      Provisioned dev-keys require the `includes` scope if building from Canvas sections is required. Without this scope, the :py:func:`get_course_groups` function will succeed but groups derived from sections will not be returned.


   Basic configuration to pull groups from Canvas courses, user groups, and sections, is as follows:

   .. code-block:: python

      from jupyterhub_oauthenticator_authz_helpers.canvas import get_user_groups, get_course_groups, build_auth_urls

      canvas_url = "<CANVAS-URL>"

      async def auth_state_hook(authenticator, auth_state):
        if auth_state is None:
          return None

        access_token = auth_state["access_token"]
        auth_state[authenticator.auth_state_groups_key] = [
          # Populate groups from Canvas courses, using the scheme defined in get_course_groups
          *await get_course_groups(canvas_url, access_token, canvas_course_key="course_code", canvas_section_key="id"),
          # Populate groups from Canvas groups, using the scheme defined in get_user_group
          *await get_user_groups(canvas_url, access_token),
        ]
        return auth_state

      cfg = c.GenericOAuthenticator
      # Inject auth state
      cfg.modify_auth_state_hook = auth_state_hook
      # Define a custom key for auth groups
      cfg.auth_state_groups_key = "custom-groups"
      # Configure auth and other URLs
      cfg.authorize_url, cfg.token_url, cfg.userdata_url = build_auth_urls(canvas_url)
      # Scopes that this token will need, pulled from functions that we've used above
      cfg.scope = [*build_auth_urls.scopes, *get_user_groups.scopes, *get_course_groups.scopes]

.. autofunction:: jupyterhub_oauthenticator_authz_helpers.canvas.get_user_groups

.. autofunction:: jupyterhub_oauthenticator_authz_helpers.canvas.get_course_groups

.. autofunction:: jupyterhub_oauthenticator_authz_helpers.canvas.build_auth_urls

.. autoclass:: jupyterhub_oauthenticator_authz_helpers.canvas.AuthURLs