From aff3051ffa33c2c50a2504fc42b5e176be955918 Mon Sep 17 00:00:00 2001 From: Richard Nemeth Date: Thu, 19 May 2022 12:40:15 +0200 Subject: [PATCH] docs: fix docstrings --- keycloak/authorization/__init__.py | 4 +- keycloak/authorization/permission.py | 14 +++-- keycloak/authorization/policy.py | 7 ++- keycloak/connection.py | 87 +++++++++++++--------------- keycloak/keycloak_openid.py | 51 ++++++++-------- 5 files changed, 79 insertions(+), 84 deletions(-) diff --git a/keycloak/authorization/__init__.py b/keycloak/authorization/__init__.py index dad1078..789656d 100644 --- a/keycloak/authorization/__init__.py +++ b/keycloak/authorization/__init__.py @@ -38,7 +38,7 @@ class Authorization: """ def __init__(self): - self._policies = {} + self.policies = {} @property def policies(self): @@ -53,7 +53,7 @@ class Authorization: Load policies, roles and permissions (scope/resources). :param data: keycloak authorization data (dict) - :return: + :returns: None """ for pol in data["policies"]: if pol["type"] == "role": diff --git a/keycloak/authorization/permission.py b/keycloak/authorization/permission.py index 9988730..a200afe 100644 --- a/keycloak/authorization/permission.py +++ b/keycloak/authorization/permission.py @@ -26,15 +26,19 @@ class Permission: """ Consider this simple and very common permission: - A permission associates the object being protected with the policies that must be evaluated to determine whether access is granted. + A permission associates the object being protected with the policies that must be evaluated to + determine whether access is granted. X CAN DO Y ON RESOURCE Z - where … - X represents one or more users, roles, or groups, or a combination of them. You can + where + + - X represents one or more users, roles, or groups, or a combination of them. You can also use claims and context here. - Y represents an action to be performed, for example, write, view, and so on. - Z represents a protected resource, for example, "/accounts". + + - Y represents an action to be performed, for example, write, view, and so on. + + - Z represents a protected resource, for example, "/accounts". https://keycloak.gitbooks.io/documentation/authorization_services/topics/permission/overview.html diff --git a/keycloak/authorization/policy.py b/keycloak/authorization/policy.py index 4fbe913..4014b7a 100644 --- a/keycloak/authorization/policy.py +++ b/keycloak/authorization/policy.py @@ -29,9 +29,10 @@ class Policy: A policy defines the conditions that must be satisfied to grant access to an object. Unlike permissions, you do not specify the object being protected but rather the conditions that must be satisfied for access to a given object (for example, resource, scope, or both). - Policies are strongly related to the different access control mechanisms (ACMs) that you can use to - protect your resources. With policies, you can implement strategies for attribute-based access control - (ABAC), role-based access control (RBAC), context-based access control, or any combination of these. + Policies are strongly related to the different access control mechanisms (ACMs) that you can + use to protect your resources. With policies, you can implement strategies for attribute-based + access control (ABAC), role-based access control (RBAC), context-based access control, or any + combination of these. https://keycloak.gitbooks.io/documentation/authorization_services/topics/policy/overview.html diff --git a/keycloak/connection.py b/keycloak/connection.py index 8ef45b1..0757377 100644 --- a/keycloak/connection.py +++ b/keycloak/connection.py @@ -33,13 +33,14 @@ from .exceptions import KeycloakConnectionError class ConnectionManager(object): - """Represents a simple server connection. - Args: - base_url (str): The server URL. - headers (dict): The header parameters of the requests to the server. - timeout (int): Timeout to use for requests to the server. - verify (bool): Verify server SSL. - proxies (dict): The proxies servers requests is sent by. + """ + Represents a simple server connection. + + :param base_url: (str) The server URL. + :param headers: (dict) The header parameters of the requests to the server. + :param timeout: (int) Timeout to use for requests to the server. + :param verify: (bool) Verify server SSL. + :param proxies: (dict) The proxies servers requests is sent by. """ def __init__(self, base_url, headers={}, timeout=60, verify=True, proxies=None): @@ -108,11 +109,11 @@ class ConnectionManager(object): self._headers = value def param_headers(self, key): - """Return a specific header parameter. - :arg - key (str): Header parameters key. - :return: - If the header parameters exist, return its value. + """ + Return a specific header parameter. + + :param key: (str) Header parameters key. + :returns: If the header parameters exist, return its value. """ return self.headers.get(key) @@ -122,36 +123,33 @@ class ConnectionManager(object): def exist_param_headers(self, key): """Check if the parameter exists in the header. - :arg - key (str): Header parameters key. - :return: - If the header parameters exist, return True. + + :param key: (str) Header parameters key. + :returns: If the header parameters exist, return True. """ return self.param_headers(key) is not None def add_param_headers(self, key, value): """Add a single parameter inside the header. - :arg - key (str): Header parameters key. - value (str): Value to be added. + + :param key: (str) Header parameters key. + :param value: (str) Value to be added. """ self.headers[key] = value def del_param_headers(self, key): """Remove a specific parameter. - :arg - key (str): Key of the header parameters. + + :param key: (str) Key of the header parameters. """ self.headers.pop(key, None) def raw_get(self, path, **kwargs): """Submit get request to the path. - :arg - path (str): Path for request. - :return - Response the request. - :exception - HttpError: Can't connect to server. + + :param path: (str) Path for request. + :returns: Response the request. + :raises: HttpError Can't connect to server. """ try: @@ -167,13 +165,11 @@ class ConnectionManager(object): def raw_post(self, path, data, **kwargs): """Submit post request to the path. - :arg - path (str): Path for request. - data (dict): Payload for request. - :return - Response the request. - :exception - HttpError: Can't connect to server. + + :param path: (str) Path for request. + :param data: (dict) Payload for request. + :returns: Response the request. + :raises: HttpError Can't connect to server. """ try: return self._s.post( @@ -189,13 +185,11 @@ class ConnectionManager(object): def raw_put(self, path, data, **kwargs): """Submit put request to the path. - :arg - path (str): Path for request. - data (dict): Payload for request. - :return - Response the request. - :exception - HttpError: Can't connect to server. + + :param path: (str) Path for request. + :param data: (dict) Payload for request. + :returns: Response the request. + :raises: HttpError Can't connect to server. """ try: return self._s.put( @@ -212,13 +206,10 @@ class ConnectionManager(object): def raw_delete(self, path, data={}, **kwargs): """Submit delete request to the path. - :arg - path (str): Path for request. - data (dict): Payload for request. - :return - Response the request. - :exception - HttpError: Can't connect to server. + :param path: (str) Path for request. + :param data: (dict) Payload for request. + :returns: Response the request. + :raises: HttpError Can't connect to server. """ try: return self._s.delete( diff --git a/keycloak/keycloak_openid.py b/keycloak/keycloak_openid.py index d9c068f..4205b0b 100644 --- a/keycloak/keycloak_openid.py +++ b/keycloak/keycloak_openid.py @@ -49,6 +49,18 @@ from .urls_patterns import ( class KeycloakOpenID: + """ + Keycloak OpenID client. + + :param server_url: Keycloak server url + :param client_id: client id + :param realm_name: realm name + :param client_secret_key: client secret key + :param verify: True if want check connection SSL + :param custom_headers: dict of custom header to pass to each HTML request + :param proxies: dict of proxies to sent the request by. + """ + def __init__( self, server_url, @@ -59,28 +71,15 @@ class KeycloakOpenID: custom_headers=None, proxies=None, ): - """ - - :param server_url: Keycloak server url - :param client_id: client id - :param realm_name: realm name - :param client_secret_key: client secret key - :param verify: True if want check connection SSL - :param custom_headers: dict of custom header to pass to each HTML request - :param proxies: dict of proxies to sent the request by. - """ - self._client_id = client_id - self._client_secret_key = client_secret_key - self._realm_name = realm_name - headers = dict() - if custom_headers is not None: - # merge custom headers to main headers - headers.update(custom_headers) - self._connection = ConnectionManager( + self.client_id = client_id + self.client_secret_key = client_secret_key + self.realm_name = realm_name + headers = custom_headers if custom_headers is not None else dict() + self.connection = ConnectionManager( base_url=server_url, headers=headers, timeout=60, verify=verify, proxies=proxies ) - self._authorization = Authorization() + self.authorization = Authorization() @property def client_id(self): @@ -206,8 +205,8 @@ class KeycloakOpenID: :param password: :param grant_type: :param code: - :param redirect_uri - :param totp + :param redirect_uri: + :param totp: :return: """ params_path = {"realm-name": self.realm_name} @@ -312,9 +311,9 @@ class KeycloakOpenID: """ Client applications can use a specific endpoint to obtain a special security token called a requesting party token (RPT). This token consists of all the entitlements - (or permissions) for a user as a result of the evaluation of the permissions and authorization - policies associated with the resources being requested. With an RPT, client applications can - gain access to protected resources at the resource server. + (or permissions) for a user as a result of the evaluation of the permissions and + authorization policies associated with the resources being requested. With an RPT, + client applications can gain access to protected resources at the resource server. :return: """ @@ -329,8 +328,8 @@ class KeycloakOpenID: def introspect(self, token, rpt=None, token_type_hint=None): """ - The introspection endpoint is used to retrieve the active state of a token. It is can only be - invoked by confidential clients. + The introspection endpoint is used to retrieve the active state of a token. + It is can only be invoked by confidential clients. https://tools.ietf.org/html/rfc7662