refactor: separate deprecated config for readability

docs/source/conf.py

@@ -94,6 +94,19 @@ def render_autodoc_modules():
 render_autodoc_modules()
 
 
+# -- Add versionremoved directive ---------------------------------------------------
+# ref: https://github.com/sphinx-doc/sphinx/issues/11480
+#
+from sphinx.domains.changeset import VersionChange, versionlabel_classes, versionlabels
+
+
+def setup(app):
+    if "versionremoved" not in versionlabels:
+        versionlabels["versionremoved"] = "Removed in version %s"
+        versionlabel_classes["versionremoved"] = "removed"
+        app.add_directive("versionremoved", VersionChange)
+
+
 # -- General Sphinx configuration ---------------------------------------------------
 # ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 #

oauthenticator/auth0.py

@@ -10,11 +10,6 @@
 
 
 class Auth0OAuthenticator(OAuthenticator):
-    _deprecated_oauth_aliases = {
-        "username_key": ("username_claim", "16.0.0"),
-        **OAuthenticator._deprecated_oauth_aliases,
-    }
-
     user_auth_state_key = "auth0_user"
 
     @default("login_service")
@@ -60,13 +55,6 @@ def _auth0_subdomain_default(self):
         # This is allowed to be empty unless auth0_domain is not supplied either
         return os.getenv("AUTH0_SUBDOMAIN", "")
 
-    username_key = Unicode(
-        config=True,
-        help="""
-        Deprecated, use `Auth0OAuthenticator.username_claim`
-        """,
-    )
-
     @default("logout_redirect_url")
     def _logout_redirect_url_default(self):
         return f"https://{self.auth0_domain}/v2/logout"
@@ -83,6 +71,20 @@ def _token_url_default(self):
     def _userdata_url_default(self):
         return f"https://{self.auth0_domain}/userinfo"
 
+    # _deprecated_oauth_aliases is used by deprecation logic in OAuthenticator
+    _deprecated_oauth_aliases = {
+        "username_key": ("username_claim", "16.0.0"),
+        **OAuthenticator._deprecated_oauth_aliases,
+    }
+    username_key = Unicode(
+        config=True,
+        help="""
+        .. deprecated:: 16.0
+
+           Use :attr:`username_claim`.
+        """,
+    )
+
 
 class LocalAuth0OAuthenticator(LocalAuthenticator, Auth0OAuthenticator):
     """A version that mixes in local system user creation"""

oauthenticator/bitbucket.py

@@ -11,11 +11,6 @@
 
 
 class BitbucketOAuthenticator(OAuthenticator):
-    _deprecated_oauth_aliases = {
-        "team_whitelist": ("allowed_teams", "0.12.0"),
-        **OAuthenticator._deprecated_oauth_aliases,
-    }
-
     client_id_env = "BITBUCKET_CLIENT_ID"
     client_secret_env = "BITBUCKET_CLIENT_SECRET"
     user_auth_state_key = "bitbucket_user"
@@ -36,17 +31,24 @@ def _token_url_default(self):
     def _userdata_url_default(self):
         return "https://api.bitbucket.org/2.0/user"
 
-    team_whitelist = Set(
+    allowed_teams = Set(
         config=True,
         help="""
-        Deprecated, use `BitbucketOAuthenticator.allowed_teams`
+        Allow members of selected Bitbucket teams to sign in.
         """,
     )
 
-    allowed_teams = Set(
+    # _deprecated_oauth_aliases is used by deprecation logic in OAuthenticator
+    _deprecated_oauth_aliases = {
+        "team_whitelist": ("allowed_teams", "0.12.0"),
+        **OAuthenticator._deprecated_oauth_aliases,
+    }
+    team_whitelist = Set(
         config=True,
         help="""
-        Allow members of selected Bitbucket teams to sign in.
+        .. deprecated:: 0.12
+
+           Use :attr:`allowed_teams`.
         """,
     )
 

oauthenticator/cilogon.py

@@ -40,22 +40,6 @@ def authorize_redirect(self, *args, **kwargs):
 
 
 class CILogonOAuthenticator(OAuthenticator):
-    _deprecated_oauth_aliases = {
-        # <deprecated-config>:
-        #   (
-        #    <new-config>,
-        #    <deprecation-version>,
-        #    <deprecated-config-and-new-config-have-same-type>
-        #   )
-        "idp_whitelist": ("allowed_idps", "0.12.0", False),
-        "idp": ("shown_idps", "15.0.0", False),
-        "strip_idp_domain": ("allowed_idps", "15.0.0", False),
-        "shown_idps": ("allowed_idps", "16.0.0", False),
-        "username_claim": ("allowed_idps", "16.0.0", False),
-        "additional_username_claims": ("allowed_idps", "16.0.0", False),
-        **OAuthenticator._deprecated_oauth_aliases,
-    }
-
     login_handler = CILogonLoginHandler
 
     user_auth_state_key = "cilogon_user"
@@ -87,14 +71,6 @@ def _token_url(self):
     def _userdata_url_default(self):
         return f"https://{self.cilogon_host}/oauth2/userinfo"
 
-    @default("username_claim")
-    def _username_claim_default(self):
-        """What keys are available will depend on the scopes requested.
-        See https://www.cilogon.org/oidc for details.
-        Note that this option can be overridden for specific identity providers via `allowed_idps[<identity provider>]["username_derivation"]["username_claim"]`.
-        """
-        return "eppn"
-
     scope = List(
         Unicode(),
         default_value=['openid', 'email', 'org.cilogon.userinfo', 'profile'],
@@ -128,13 +104,6 @@ def _validate_scope(self, proposal):
 
         return scopes
 
-    idp_whitelist = List(
-        config=True,
-        help="""
-        Deprecated, use `CIlogonOAuthenticator.allowed_idps`
-        """,
-    )
-
     allowed_idps = Dict(
         config=True,
         help="""
@@ -159,44 +128,43 @@ def _validate_scope(self, proposal):
                     "username_derivation": {
                         "username_claim": "username",
                         "action": "prefix",
-                        "prefix": "gh",
+                        "prefix": "github",
                     },
                 },
                 "http://google.com/accounts/o8/id": {
                     "username_derivation": {
                         "username_claim": "username",
+                        "action": "prefix",
+                        "prefix": "google",
                     },
                     "allowed_domains": ["uni.edu", "something.org"],
                 },
             }
 
         Where `username_derivation` defines:
-            * :attr:`username_claim`: string
+
+            * `username_claim`: string (required)
                 The claim in the `userinfo` response from which to get the
                 JupyterHub username. Examples include: `eppn`, `email`. What
-                keys are available will depend on the scopes requested. It will
-                overwrite any value set through
-                CILogonOAuthenticator.username_claim for this identity provider.
-            * :attr:`action`: string What action to perform on the username.
-                Available options are "strip_idp_domain", which will strip the
-                domain from the username if specified and "prefix", which will
-                prefix the hub username with "prefix:".
-            * :attr:`domain:` string
+                keys are available will depend on the scopes requested.
+            * `action`: string
+                What action to perform on the username. Available options are
+                "strip_idp_domain", which will strip the domain from the
+                username if specified and "prefix", which will prefix the hub
+                username with "prefix:".
+            * `domain:` string (required if action is strip_idp_domain)
                 The domain after "@" which will be stripped from the username if
                 it exists and if the action is "strip_idp_domain".
-            * :attr:`prefix`: string The prefix which will be added at the
-                beginning of the username followed by a semi-column ":", if the
-                action is "prefix".
-            * :attr:`allowed_domains`: string It defines which domains will be
-                allowed to login using the specific identity provider.
-
-        Requirements:
-            * if `username_derivation.action` is `strip_idp_domain`, then `username_derivation.domain` must also be specified
-            * if `username_derivation.action` is `prefix`, then `username_derivation.prefix` must also be specified.
-            * `username_claim` must be provided for each idp in `allowed_idps`
-
-        .. versionchanged:: 15.0.0
-            `CILogonOAuthenticaor.allowed_idps` changed type from list to dict
+            * `prefix`: string (required if action is prefix)
+                The prefix which will be added at the beginning of the username
+                followed by a semi-column ":", if the action is "prefix".
+            * `allowed_domains`: string
+                It defines which domains will be allowed to login using the
+                specific identity provider.
+
+        .. versionchanged:: 15.0
+
+           Changed format from a list to a dictionary.
         """,
     )
 
@@ -231,58 +199,72 @@ def _validate_allowed_idps(self, proposal):
 
         return idps
 
-    strip_idp_domain = Bool(
-        False,
+    skin = Unicode(
         config=True,
         help="""
-        Deprecated, use `CILogonOAuthenticator.allowed_idps[<ipd>]["username_derivation"]["action"] = "strip_idp_domain"`
-        to enable it and `CIlogonOAuthenticator.allowed_idps[<idp>]["username_derivation"]["domain"]` to list the domain
-        which will be stripped
+        The `skin` attribute is the name of the custom CILogon interface skin
+        for your application.
+
+        Contact [email protected] to request a custom skin.
         """,
     )
 
-    idp = Unicode(
+    # _deprecated_oauth_aliases is used by deprecation logic in OAuthenticator
+    _deprecated_oauth_aliases = {
+        "idp_whitelist": ("allowed_idps", "0.12.0", False),
+        "idp": ("shown_idps", "15.0.0", False),
+        "strip_idp_domain": ("allowed_idps", "15.0.0", False),
+        "shown_idps": ("allowed_idps", "16.0.0", False),
+        "additional_username_claims": ("allowed_idps", "16.0.0", False),
+        "username_claim": ("allowed_idps", "16.0.0", False),
+        **OAuthenticator._deprecated_oauth_aliases,
+    }
+    idp_whitelist = List(
         config=True,
         help="""
-        Deprecated, use `CILogonOAuthenticator.shown_idps`.
+        .. versionremoved:: 0.12
+
+           Use :attr:`allowed_idps`.
         """,
     )
-
-    shown_idps = List(
-        Unicode(),
+    idp = Unicode(
         config=True,
         help="""
-        Deprecated, `CILogonOAuthenticator.allowed_idps` will determine the idps
-        shown.
-
-        A list of identity providers to be shown as login options. The `idp`
-        attribute is the SAML Entity ID of the user's selected identity
-        provider.
+        .. versionremoved:: 15.0
 
-        See https://cilogon.org/include/idplist.xml for the list of identity
-        providers supported by CILogon.
+           Use :attr:`allowed_idps`.
         """,
     )
-
-    skin = Unicode(
+    strip_idp_domain = Bool(
         config=True,
         help="""
-        The `skin` attribute is the name of the custom CILogon interface skin
-        for your application.
+        .. versionremoved:: 15.0
 
-        Contact [email protected] to request a custom skin.
+           Use :attr:`allowed_idps`.
         """,
     )
+    shown_idps = List(
+        config=True,
+        help="""
+        .. versionremoved:: 16.0
 
+           Use :attr:`allowed_idps`.
+        """,
+    )
     additional_username_claims = List(
         config=True,
         help="""
-        Deprecated, use `CILogonOAuthenticator.allowed_idps["username_derivation"]["username_claim"]`.
+        .. versionremoved:: 16.0
 
-        Additional claims to check if the username_claim fails.
+           Use :attr:`allowed_idps`.
+        """,
+    )
+    username_claim = Unicode(
+        config=True,
+        help="""
+        .. versionremoved:: 16.0
 
-        This is useful for linked identities where not all of them return the
-        primary username_claim.
+           Use :attr:`allowed_idps`.
         """,
     )
 

oauthenticator/generic.py

@@ -13,19 +13,6 @@
 
 
 class GenericOAuthenticator(OAuthenticator):
-    _deprecated_oauth_aliases = {
-        "username_key": ("username_claim", "16.0.0"),
-        "extra_params": ("token_params", "16.0.0"),
-        **OAuthenticator._deprecated_oauth_aliases,
-    }
-
-    extra_params = Dict(
-        config=True,
-        help="""
-        Deprecated, use `GenericOAuthenticator.token_params`
-        """,
-    )
-
     @default("login_service")
     def _login_service_default(self):
         return os.environ.get("LOGIN_SERVICE", "OAuth 2.0")
@@ -69,12 +56,6 @@ def _login_service_default(self):
         """,
     )
 
-    username_key = Union(
-        [Unicode(os.environ.get('OAUTH2_USERNAME_KEY', 'username')), Callable()],
-        config=True,
-        help="""Deprecated, use `GenericOAuthenticator.username_claim`""",
-    )
-
     username_claim = Union(
         [Unicode(os.environ.get('OAUTH2_USERNAME_KEY', 'username')), Callable()],
         config=True,
@@ -105,6 +86,30 @@ def _default_http_client(self):
             force_instance=True, defaults=dict(validate_cert=self.tls_verify)
         )
 
+    # _deprecated_oauth_aliases is used by deprecation logic in OAuthenticator
+    _deprecated_oauth_aliases = {
+        "username_key": ("username_claim", "16.0.0"),
+        "extra_params": ("token_params", "16.0.0"),
+        **OAuthenticator._deprecated_oauth_aliases,
+    }
+    username_key = Union(
+        [Unicode(), Callable()],
+        config=True,
+        help="""
+        .. deprecated:: 16.0
+
+           Use :attr:`username_claim`.
+        """,
+    )
+    extra_params = Dict(
+        config=True,
+        help="""
+        .. deprecated:: 16.0
+
+           Use :attr:`token_params`.
+        """,
+    )
+
     def user_info_to_username(self, user_info):
         """
         Overrides OAuthenticator.user_info_to_username to support the