Merge branch 'devel' into rtfd

dpl/api/api_gateway.py

@@ -27,6 +27,7 @@ def __init__(self, auth_manager: AuthManager, platform_manager: PlatformManager,
     def auth(self, username: str, password: str) -> str:
         """
         Authenticate user and receive corresponding access token
+
         :param username: username of the user
         :param password: password of the user
         :return: an access token to be used
@@ -36,6 +37,7 @@ def auth(self, username: str, password: str) -> str:
     def _check_permission(self, token: str, requested_action):
         """
         Checks is specified action is permitted for this token
+
         :param token: access token to be checked
         :param requested_action: information about a requested action or permission
         :return: None
@@ -50,6 +52,7 @@ def _thing_to_dict(self, thing: Thing) -> dict:
 
         In addition to simple object -> dict serialization, the content of 'metadata'
         property will be moved to resulting dict body.
+
         :param thing: an instance of Thing to be converted
         :return: a corresponding dict
         """
@@ -64,6 +67,7 @@ def _thing_to_dict(self, thing: Thing) -> dict:
     def get_things(self, token: str) -> List[Dict]:
         """
         Receive a full list of data about things
+
         :param token: access token
         :return: a list of things data
         """
@@ -80,6 +84,7 @@ def get_things(self, token: str) -> List[Dict]:
     def _get_thing(self, token: str, thing_id: str) -> Thing:
         """
         Private method. Receive an instance of a specific thing
+
         :param token: access token
         :param thing_id: an ID of thing to be fetched
         :return: an instance of Thing that is related to the specified ID
@@ -97,6 +102,7 @@ def _get_thing(self, token: str, thing_id: str) -> Thing:
     def get_thing(self, token: str, thing_id: str) -> Dict:
         """
         Receive information about a specific thing
+
         :param token: access token
         :param thing_id: an ID of thing to be fetched
         :return: a dict with full information about the thing
@@ -113,6 +119,7 @@ def get_thing(self, token: str, thing_id: str) -> Dict:
     def send_command(self, token: str, thing_id: str, command: str, *args, **kwargs):
         """
         Sends a command to specific thing with specified arguments
+
         :param token: access token
         :param thing_id: and ID of thing that must receive a specified command
         :param command: command to execute
@@ -145,6 +152,7 @@ def send_command(self, token: str, thing_id: str, command: str, *args, **kwargs)
     def get_task_status(self, token: str, task_id):
         """
         Get a status of a planned task
+
         :param token: an access token
         :param task_id: some id or handler of task to be fetched
         :return: a status of the task
@@ -155,6 +163,7 @@ def get_task_status(self, token: str, task_id):
     def _placement_to_dict(cls, placement: Placement) -> Dict:
         """
         Converts an instance of Placement to corresponding dictionary
+
         :return: a dictionary with all properties of placement
         """
         # FIXME: CC14: Consider switching to direct usage of properties
@@ -170,6 +179,7 @@ def _placement_to_dict_legacy(cls, placement: Placement) -> Dict:
         Converts an instance of Placement to corresponding dictionary that is compatible
         with the legacy API ('description' field will be set to the value of 'friendly_name' field,
         'image' field will be set to a value of 'image_url' field).
+
         :return: a dictionary with all properties of placement
         """
         warnings.warn("Legacy representation of placements will be dropped in the next release"
@@ -186,6 +196,7 @@ def _placement_to_dict_legacy(cls, placement: Placement) -> Dict:
     def get_placements(self, token: str) -> List[Dict]:
         """
         Returns a list of dict-like representations of all placements
+
         :param token: access token
         :return: a list of placements data
         """
@@ -202,6 +213,7 @@ def get_placements(self, token: str) -> List[Dict]:
     def get_placement(self, token: str, placement_id: str) -> Dict:
         """
         Returns a dict-like representation of placement with the specified ID
+
         :param token: access token
         :param placement_id: an ID of placement to be fetched
         :return: a dict with full information about the placement

dpl/api/rest_api.py

@@ -43,6 +43,7 @@ def make_json_response(content: object, status: int = 200) -> web.Response:
     custom JSON encoders by default (functools.partial() may be used to create a
     corresponding callable which must to be passed into 'json_response' function
     as 'dumps' keyword argument).
+
     :param content: content to serialize
     :param status: status code of the response
     :return: created response
@@ -96,6 +97,7 @@ def __init__(self, gateway: ApiGateway, loop=None):
         """
         Constructor. Receives a reference to API Gateway that will receive and process all
         command and data requests. Setups API routes and request handlers.
+
         :param gateway: an instance of ApiGateway
         """
         self._gateway = gateway
@@ -126,6 +128,7 @@ def __init__(self, gateway: ApiGateway, loop=None):
     async def create_server(self, host: str, port: int) -> None:
         """
         Factory function that creates fully-functional aiohttp server
+
         :param host: a server hostname or address
         :param port: a server port
         :return: None
@@ -137,6 +140,7 @@ async def shutdown_server(self) -> None:
         """
         Stop (shutdown) REST server gracefully.
         More info is available here: http://aiohttp.readthedocs.io/en/stable/web.html#aiohttp-web-graceful-shutdown
+
         :return: None
         """
         self._server.close()
@@ -149,6 +153,7 @@ async def shutdown_server(self) -> None:
     async def _middleware_process_exceptions(app, handler):
         """
         Factory method that returns a handler coroutine for all unprocessed exceptions
+
         :param app: application that is related to this middleware
         :param handler: a handler to be wrapped; original request handler
         :return: a coroutine, middleware handler
@@ -188,6 +193,7 @@ async def middleware_handler(request: web.Request) -> web.Response:
     async def root_get_handler(self, request: web.Request) -> web.Response:
         """
         A handler for GET requests to path='/'
+
         :param request: request to be processed
         :return: a response to request
         """
@@ -202,6 +208,7 @@ async def root_get_handler(self, request: web.Request) -> web.Response:
     async def auth_post_handler(self, request: web.Request, json_data: dict = None) -> web.Response:
         """
         Primitive username and password validator
+
         :param request: request to be processed
         :param json_data: a content of request body
         :return: a response to request
@@ -230,6 +237,7 @@ async def auth_options_handler(self, request: web.Request) -> web.Response:
         A handler for OPTIONS request for path /auth.
 
         Returns a response that contains 'Allow' header with all allowed HTTP methods.
+
         :param request: request to be handled
         :return: a response to request
         """
@@ -243,6 +251,7 @@ async def auth_options_handler(self, request: web.Request) -> web.Response:
     async def things_get_handler(self, request: web.Request, token: str = None) -> web.Response:
         """
         A handler for GET requests for path /things/
+
         :param request: request to be processed
         :param token: an access token to be used, usually fetched by restricted_access_decorator
         :return: a response to request
@@ -263,6 +272,7 @@ def _get_thing_id(self, request: web.Request) -> str:
     async def thing_get_handler(self, request: web.Request, token: str = None) -> web.Response:
         """
         A handler for GET requests for path /things/
+
         :param request: request to be processed
         :param token: an access token to be used, usually fetched by restricted_access_decorator
         :return: a response to request
@@ -287,6 +297,7 @@ async def thing_get_handler(self, request: web.Request, token: str = None) -> we
     async def placements_get_handler(self, request: web.Request, token: str = None) -> web.Response:
         """
         A handler for GET requests for path /placements/
+
         :param request: request to be processed
         :param token: an access token to be used, usually fetched by restricted_access_decorator
         :return: a response to request
@@ -310,6 +321,7 @@ def _get_placement_id(self, request: web.Request) -> str:
     async def placement_get_handler(self, request: web.Request, token: str = None) -> web.Response:
         """
         A handler for GET requests for path /placements/
+
         :param request: request to be processed
         :param token: an access token to be used, usually fetched by restricted_access_decorator
         :return: a response to request
@@ -337,6 +349,7 @@ async def messages_post_handler(self, request: web.Request, token: str = None, j
         """
         ONLY FOR COMPATIBILITY: Accept 'action requested' messages from clients.
         Handle POST requests for /messages/ path.
+
         :param request: request to be processed
         :param token: an access token to be used, usually fetched by restricted_access_decorator
         :return: a response to request
@@ -426,6 +439,7 @@ async def messages_options_handler(self, request: web.Request) -> web.Response:
         A handler for OPTIONS request for path /messages/.
 
         Returns a response that contains 'Allow' header with all allowed HTTP methods.
+
         :param request: request to be handled
         :return: a response to request
         """

dpl/auth/auth_manager.py

@@ -22,6 +22,7 @@ def __init__(self):
     def users(self) -> Set[str]:
         """
         Returns a set of registered usernames
+
         :return: usernames of all registered users
         """
         # FIXME: CC7: Return just plain keys(), as is
@@ -31,6 +32,7 @@ def users(self) -> Set[str]:
     def create_root_user(self, username: str, password: str):
         """
         Create a root user if there is no users registered
+
         :param username: a username of root user
         :param password: a password of root user
         :return: None
@@ -50,6 +52,7 @@ def create_root_user(self, username: str, password: str):
     def create_user(self, token: str, username: str, password: str):
         """
         Create a user with specified username and password values
+
         :param token: an access token of a user that is trying to create a new one
         :param username: username of the user to be created
         :param password: password of the user to be created
@@ -69,6 +72,7 @@ def _check_if_authorized_to_manipulate_users(self, token: str):
         """
         Checks if user with specified token is authorized to create or remove users.
         Otherwise raises an exception.
+
         :param token: an access token of a user that is trying to create or remove another one
         :return: None
         """
@@ -84,6 +88,7 @@ def _check_if_authorized_to_manipulate_users(self, token: str):
     def remove_user(self, token: str, username: str):
         """
         Remove a user from the system
+
         :param token: an access token of a user that is trying to remove someone
         :param username: a username of the user to be removed
         :return: None
@@ -105,6 +110,7 @@ def remove_user(self, token: str, username: str):
     def change_password(self, username: str, old_password: str, new_password: str):
         """
         Change a password of specific user
+
         :param username: a username of user whose password must be changed
         :param old_password: an old password of this user
         :param new_password: a new password of this user
@@ -123,6 +129,7 @@ def change_password(self, username: str, old_password: str, new_password: str):
     def _check_user_registered(self, username):
         """
         Checks if the user is registered in the system. Otherwise raises an exception
+
         :param username: username of user to be checked
         :return: None
         """
@@ -132,6 +139,7 @@ def _check_user_registered(self, username):
     def auth_user(self, username: str, password: str) -> str:
         """
         Authenticate the user and receive an access token for future usages
+
         :param username: username of user to be authenticated
         :param password: password of user to be authenticated
         :return: an access token
@@ -152,6 +160,7 @@ def auth_user(self, username: str, password: str) -> str:
     def is_token_grants(self, token: str, requested_action: object) -> bool:
         """
         Check if specified token grants to perform the requested action
+
         :param token: an access token
         :param requested_action: an info about the requested action
         :return: true if permission is granted, false otherwise

dpl/auth/token_manager.py

@@ -25,6 +25,7 @@ def __init__(self):
     def generate_token(self, token_owner) -> str:
         """
         Generates a new token for some User (or Client)
+
         :param token_owner: User or Client which is associated with token
         :return: a new token
         """
@@ -41,6 +42,7 @@ def generate_token(self, token_owner) -> str:
     def remove_token(self, token: str):
         """
         Revoke generated token
+
         :param token: a token to be revoked
         :return: None
         """
@@ -52,6 +54,7 @@ def remove_token(self, token: str):
     def remove_all_tokens(self, token_owner):
         """
         Revoke all generated tokens for specific User or Client
+
         :param token_owner: User or Client which is associated with tokens to be revoked
         :return: None
         """
@@ -74,6 +77,7 @@ def remove_all_tokens(self, token_owner):
     def resolve_token_owner(self, token: str):
         """
         Determine an owner of specified token
+
         :param token: token to be resolved
         :return: an object of User or Client that owns the token
         """
@@ -82,6 +86,7 @@ def resolve_token_owner(self, token: str):
     def is_token_present(self, token: str) -> bool:
         """
         Checks if the specified token is registered in the system
+
         :param token: token to be checked
         :return: true if token is registered, false otherwise
         """

dpl/auth/user.py

@@ -25,6 +25,7 @@ class User(object):
     def __init__(self, username: str, password: str):
         """
         Create a user of the system
+
         :param username: username to be used
         :param password: password to be used. NOT SAVED, just hashed
         """
@@ -37,6 +38,7 @@ def __init__(self, username: str, password: str):
     def username(self) -> str:
         """
         Returns a username of this user
+
         :return: username as a string
         """
         return self._username
@@ -45,6 +47,7 @@ def username(self) -> str:
     def username(self, value: str):
         """
         Updates the username of the user
+
         :param value: new username to be set
         :return: None
         """
@@ -57,6 +60,7 @@ def username(self, value: str):
     def _is_username_valid(username: str) -> bool:
         """
         Checks is the specified username is valid
+
         :param username: username to be checked
         :return: true if valid, false otherwise
         """
@@ -66,6 +70,7 @@ def _is_username_valid(username: str) -> bool:
     def verify_password(self, password: str) -> bool:
         """
         Checks is the password is correct for this user
+
         :param password: password to be checked
         :return: true if password is correct and false otherwise
         """
@@ -74,6 +79,7 @@ def verify_password(self, password: str) -> bool:
     def update_password(self, old_password: str, new_password: str):
         """
         Updates current user password, raises an error if old_password is incorrect
+
         :param old_password: old password
         :param new_password: new password to be set
         :return: None

dpl/core/configuration.py

@@ -42,6 +42,7 @@ class Configuration(object):
     def __init__(self, path: str):
         """
         Constructor which saves a path to configuration directory
+
         :param path: a path to configuration directory
         """
         check_dir_path(path)
@@ -53,6 +54,7 @@ def __init__(self, path: str):
     def load_config(self) -> None:
         """
         Loads configuration from disk to memory
+
         :return: None
         """
         # TODO: REWRITE
@@ -76,13 +78,15 @@ def load_config(self) -> None:
     def save_config(self) -> None:
         """
         Saves configuration on disk
+
         :return: None
         """
         raise NotImplementedError
 
     def get_by_subsystem(self, subsystem_name: str) -> Dict or List[Dict]:
         """
         Returns a dict or list of config values that is related to specific subsystem
+
         :param subsystem_name: subsystem name for request
         :return: configuration values that are related to specified subsystem
         """