TokenPayload#

def has_scopes(self, *scopes: str, all_required: bool = True) -> bool:
    """Check if the token contains the specified scopes.

    Verifies whether the token's scopes satisfy the required scope values.
    Supports wildcard matching where a scope ending with ":*" matches
    any scope under that namespace (e.g., "admin:*" matches "admin:users").

    Args:
        *scopes: Variable number of scope strings to check against the token's scopes.
        all_required: If True (default), all scopes must be present (AND logic).
                     If False, at least one scope must be present (OR logic).

    Returns:
        A boolean indicating whether the scope requirements are satisfied.

    Examples:
        >>> payload.scopes = ["users:read", "posts:write"]
        >>> payload.has_scopes("users:read")
        True
        >>> payload.has_scopes("users:read", "posts:write")
        True
        >>> payload.has_scopes("admin")
        False

        # With wildcard scopes in token
        >>> payload.scopes = ["admin:*"]
        >>> payload.has_scopes("admin:users")
        True
        >>> payload.has_scopes("admin:settings")
        True

        # OR logic
        >>> payload.scopes = ["read"]
        >>> payload.has_scopes("read", "admin", all_required=False)
        True
    """
    return has_required_scopes(list(scopes), self.scopes, all_required=all_required)

def encode(
    self,
    key: str,
    algorithm: AlgorithmType = "HS256",
    ignore_errors: bool = True,
    headers: Optional[dict[str, Any]] = None,
    data: Optional[dict[str, Any]] = None,
) -> str:
    """Generate a JSON Web Token (JWT) with the current payload's claims and configuration.

    Creates a signed token using the specified cryptographic key and algorithm, incorporating all token metadata.

    Args:
        key: The cryptographic key used for token signing.
        algorithm: The cryptographic algorithm for token signing. Defaults to HS256.
        ignore_errors: Flag to suppress potential encoding errors. Defaults to True.
        headers: Optional custom headers to include in the token.
        data: Optional additional data to embed in the token.

    Returns:
        A string representing the encoded and signed JWT.
    """
    # Include scopes in data if present
    token_data = data.copy() if data else {}
    if self.scopes is not None:
        token_data["scopes"] = self.scopes

    return create_token(
        key=key,
        algorithm=algorithm,
        uid=str(self.sub),
        jti=self.jti,
        issued=self.iat,
        # TODO: Fix type hinting for `type` Field
        # it's caused because Type is a string & what we expect is a TokenType
        # TokenType = Literal["access", "refresh"]
        # Investigate if it's possible to fix this
        type=self.type,  # type: ignore
        expiry=self.exp,
        fresh=self.fresh,
        csrf=self.csrf,
        audience=self.aud,
        issuer=self.iss,
        not_before=self.nbf,
        ignore_errors=ignore_errors,
        headers=headers,
        data=token_data if token_data else None,
    )

@classmethod
def decode(
    cls,
    token: str,
    key: str,
    algorithms: Optional[Sequence[AlgorithmType]] = None,
    audience: Optional[StringOrSequence] = None,
    issuer: Optional[str] = None,
    verify: bool = True,
) -> "TokenPayload":
    """Decode and validate a JSON Web Token (JWT) into a TokenPayload instance.

    Converts a signed token into a structured payload object, with optional verification and validation parameters.

    Args:
        token: The encoded JWT string to be decoded.
        key: The cryptographic key used for token verification.
        algorithms: Optional list of allowed cryptographic algorithms. Defaults to HS256.
        audience: Optional expected token audience.
        issuer: Optional expected token issuer.
        verify: Flag to enable or disable token verification. Defaults to True.

    Returns:
        A TokenPayload instance representing the decoded token's claims.
    """
    if algorithms is None:  # pragma: no cover
        algorithms = ["HS256"]  # pragma: no cover
    payload = decode_token(
        token=token,
        key=key,
        algorithms=algorithms,
        audience=audience,
        issuer=issuer,
        verify=verify,
    )
    return cls.model_validate(payload)