From fed7257a1a12ef2537d3abdf5a71a74c11df6f22 Mon Sep 17 00:00:00 2001 From: Musilah Date: Wed, 20 Sep 2023 04:50:54 +0300 Subject: [PATCH] fix things.py file Signed-off-by: Musilah --- docs/README.md | 2 + docs/things.md | 297 ++++++++++++++++++++++++++++++++++++++++----- mainflux/things.py | 28 ++--- 3 files changed, 280 insertions(+), 47 deletions(-) diff --git a/docs/README.md b/docs/README.md index fc15856..0ab5ddc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,6 +12,7 @@ - [`messages`](./messages.md#module-messages) - [`response`](./response.md#module-response) - [`sdk`](./sdk.md#module-sdk) +- [`things`](./things.md#module-things) - [`users`](./users.md#module-users) - [`utils`](./utils.md#module-utils) @@ -25,6 +26,7 @@ - [`response.Error`](./response.md#class-error) - [`response.Response`](./response.md#class-response) - [`sdk.SDK`](./sdk.md#class-sdk) +- [`things.Things`](./things.md#class-things): Things API client. - [`users.Users`](./users.md#class-users): Users API client. ## Functions diff --git a/docs/things.md b/docs/things.md index 37945ef..d0e74f0 100644 --- a/docs/things.md +++ b/docs/things.md @@ -14,11 +14,18 @@ ## class `Things` +Things API client. +Things API is used for creating and managing things. It is used for creating new things, creating multiple things getting thing information, updating thing information, disabling and enabling things ,and connecting and disconnecting things. - +**Attributes:** + + - `URL`: str - URL of the Things API + - `THINGS_ENDPOINT`: str - Things API endpoint + + ### method `__init__` @@ -35,7 +42,7 @@ __init__(url: str) --- - + ### method `authorise_thing` @@ -43,11 +50,28 @@ __init__(url: str) authorise_thing(access_request: dict, token: str) ``` -Authorises thing +Authorises thing. + +Creates policies for a thing as a subject over a channel which is the object. It authorizes the thing to perform some actions over the channel. + +params: + + access_request: dict - access request information for example: { "subject": "fd4f7da5-b7bf-49b7-bf2f-99995e78afd9", "object": "567f7da5-b7bf-49b7-bf2f-99995e78afd9", "actions": "m_write" "entity_type": "group" } token: str - token used for authorising thing + + + +**returns:** + + - `mf_resp`: "True" + +Usage: +``` + + >>> from mainflux import sdk >>> mfsdk = sdk.SDK(things_url="http://localhost:9000") >>> access_request = { ... "subject": "fd4f7da5-b7bf-49b7-bf2f-99995e78afd9", ... "object": "567f7da5-b7bf-49b7-bf2f-99995e78afd9", ... "actions": "m_write" ... "entity_type": "group" ... } >>> mf_resp = mfsdk.things.authorise_thing(access_request) >>> mf_resp --- - + ### method `connect` @@ -55,11 +79,26 @@ Authorises thing connect(thing_id: str, channel_id: str, action: str, token: str) ``` -Connects thing and channel +Connects thing and channel. + +Connects a thing and channel with provided thing ID as the subject, channel ID as the object, action that the thing can partake in and a valid token. + +params: thing_id: str - ID of the thing channel_id: str - ID of the channel action: str - action for example: "m_write" token: str - token used for connecting thing and channel + + + +**returns:** + + - `mf_resp`: "connected" + +Usage: +``` + + >>> from mainflux import sdk >>> mfsdk = sdk.SDK(things_url="http://localhost:9000") >>> thing_id = "fd4f7da5-b7bf-49b7-bf2f-99995e78afd9" >>> channel_id = "567f7da5-b7bf-49b7-bf2f-99995e78afd9" >>> action = "m_write" >>> mf_resp = mfsdk.things.connect(thing_id, channel_id, action) >>> mf_resp --- - + ### method `connects` @@ -67,11 +106,26 @@ Connects thing and channel connects(thing_ids: list, channel_ids: list, actions: list, token: str) ``` -Connects thing and channel +Connects things and channels. + +Connects multiple things and channels with provided thing IDs as the subjects, channel IDs as the objects, actions that the thing can partake in and a valid token. + +params: thing_ids: list - list of thing IDs channel_ids: list - list of channel IDs actions: list - list of actions for example: ["m_write", "m_read"] token: str - token used for connecting things and channels + + + +**returns:** + + - `mf_resp`: response.Response - response object. + +Usage: +``` + + >>> from mainflux import sdk >>> mfsdk = sdk.SDK(things_url="http://localhost:9000") >>> thing_ids = ["fd4f7da5-b7bf-49b7-bf2f-99995e78afd9"] >>> channel_ids = ["567f7da5-b7bf-49b7-bf2f-99995e78afd9"] >>> actions = ["m_write", "m_read"] >>> mf_resp = mfsdk.things.connects(thing_ids, channel_ids, actions) >>> mf_resp --- - + ### method `create` @@ -79,11 +133,24 @@ Connects thing and channel create(thing: dict, token: str) ``` -Creates thing entity in the database +Creates thing entity in the database. + +Creates a new thing with provided thing information. If token is provided, it will be used to create a new thing + +params: thing: dict - thing information for example: { "name": "thing1" } token: str - token used for creating a new thing + + + +**returns:** + + - `mf_resp`: response.Response - response object + +Usage: +``` >>> from mainflux import sdk >>> mfsdk = sdk.SDK(things_url="http://localhost:9000") >>> thing = { ... "name": "thing1", ... } >>> mf_resp = mfsdk.things.create(thing) >>> mf_resp --- - + ### method `create_bulk` @@ -91,11 +158,24 @@ Creates thing entity in the database create_bulk(things: list, token: str) ``` -Creates multiple things in a bulk +Creates multiple things in bulk. + +Creates multiple new things with provided things information. If a token is provided, it will be used to create the new things. + +params: things: list - a list of things with theri information for example: [ {"name": "thing2"}, {"name": "thing3"}, {"name": "thing4"} ] token: str - token used for creating the new things. + + + +**returns:** + + - `mf_resp`: response.Response - response object + +Usage: +``` >>> from mainflux import sdk >>> mfsdk = sdk.SDK(things_url="http://localhost:9000") >>> things = [ ... {"name": "thing2"}, ... {"name": "thing3"}, ... {"name": "thing4"} ... ] >>> mf_resp = mfsdk.things.create_bulk(things) >>> mf_resp --- - + ### method `disable` @@ -103,11 +183,24 @@ Creates multiple things in a bulk disable(thing_id: str, token: str) ``` -Deletes a thing entity from database +Deletes a thing entity from the database. + +Deletes a thing with provided thing ID and valid token. + +params: thing_id: str - ID of the thing token: str - token used for deleting thing + + + +**returns:** + + - `mf_resp`: response.Response - response object. + +Usage: +``` >>> from mainflux import sdk >>> mfsdk = sdk.SDK(things_url="http://localhost:9000") >>> thing_id = "fd4f7da5-b7bf-49b7-bf2f-99995e78afd9" >>> mf_resp = mfsdk.things.disable(thing_id) >>> mf_resp --- - + ### method `disconnect` @@ -115,11 +208,26 @@ Deletes a thing entity from database disconnect(thing_id: str, channel_id: str, token: str) ``` -Disconnect thing and channel +Disconnects thing and channel. + +Disconnects a thing and channel with provided thing ID as the subject, channel ID as the object and a valid token. + +params: thing_id: str - ID of the thing channel_id: str - ID of the channel token: str - token used for disconnecting thing and channel + + + +**returns:** + + - `mf_resp`: response.Response - response object. + +Usage: +``` + + >>> from mainflux import sdk >>> mfsdk = sdk.SDK(things_url="http://localhost:9000") >>> thing_id = "fd4f7da5-b7bf-49b7-bf2f-99995e78afd9" >>> channel_id = "567f7da5-b7bf-49b7-bf2f-99995e78afd9" >>> mf_resp = mfsdk.things.disconnect(thing_id, channel_id) >>> mf_resp --- - + ### method `disconnects` @@ -127,11 +235,26 @@ Disconnect thing and channel disconnects(thing_ids: list, channel_ids: list, token: str) ``` -Disconnect thing and channel +Disconnect things and channels. + +Disconnects multiple things and channels with provided thing IDs as the subjects, channel IDs as the objects and a valid token. + +params: thing_ids: list - list of thing IDs channel_ids: list - list of channel IDs token: str - token used for disconnecting things and channels + + + +**returns:** + + - `mf_resp`: response.Response - response object. + +Usage: +``` + + >>> from mainflux import sdk >>> mfsdk = sdk.SDK(things_url="http://localhost:9000") >>> thing_ids = ["fd4f7da5-b7bf-49b7-bf2f-99995e78afd9"] >>> channel_ids = ["567f7da5-b7bf-49b7-bf2f-99995e78afd9"] >>> mf_resp = mfsdk.things.disconnects(thing_ids, channel_ids) >>> mf_resp --- - + ### method `get` @@ -139,11 +262,24 @@ Disconnect thing and channel get(thing_id: str, token: str) ``` -Gets a thing entity for a logged-in user +Gets a thing entity. + +Provides information about a thing with provided thing ID and token. Information about a thing is provided in a JSON format and includes the name its owner, secret,tags and status. + +params: thing_id: str - ID of the thing token: str - token used for getting thing information + + + +**returns:** + + - `mf_resp`: response.Response - response object. + +Usage: +``` >>> from mainflux import sdk >>> mfsdk = sdk.SDK(things_url="http://localhost:9000") >>> thing_id = "fd4f7da5-b7bf-49b7-bf2f-99995e78afd9" >>> mf_resp = mfsdk.things.get(thing_id) >>> mf_resp --- - + ### method `get_all` @@ -151,11 +287,24 @@ Gets a thing entity for a logged-in user get_all(query_params: dict, token: str) ``` -Gets all things from database +Gets all things from database. + +Provides information about all things in a JSON format. It is controlled by a set of query parameters and a valid token. + +params: query_params: dict - query parameters for example: { "offset": 0, "limit": 10 } where offset is the number of things to skip and limit is the maximum token: str - token used for getting all things information + + + +**returns:** + + - `mf_resp`: response.Response - response object. + +Usage: +``` >>> from mainflux import sdk >>> mfsdk = sdk.SDK(things_url="http://localhost:9000") >>> query_params = { ... "offset": 0, ... "limit": 10 ... } >>> mf_resp = mfsdk.things.get_all(query_params) >>> mf_resp --- - + ### method `get_by_channel` @@ -163,11 +312,20 @@ Gets all things from database get_by_channel(channel_id: str, query_params: dict, token: str) ``` -Gets all things to which a specific thing is connected to +Gets all things to which a specific thing is connected to. + +Provides a list of all things that are connected to a specific channel when given a channel ID and valid token. + +params: channel_id: str - ID of the channel query_params: dict - query parameters for example: { "offset": 0, "limit": 10 } where offset is the number of things to skip and limit is the maximum token: str - token used for getting all things information + +returns: mf_resp: response.Response - response object. + +Usage: +``` >>> from mainflux import sdk >>> mfsdk = sdk.SDK(things_url="http://localhost:9000") >>> channel_id = "567f7da5-b7bf-49b7-bf2f-99995e78afd9" >>> query_params = { ... "offset": 0, ... "limit": 10 ... } >>> mf_resp = mfsdk.things.get_by_channel(channel_id, query_params) >>> mf_resp --- - + ### method `share_thing` @@ -175,11 +333,26 @@ Gets all things to which a specific thing is connected to share_thing(user_id: str, channel_id: str, actions: list, token: str) ``` -Share thing +Shares thing. + +Allows a logged in user to create new policies for a thing over a channel provided with a user ID, channel ID, actions that the thing can partake in and a valid token. + +params: user_id: str - ID of the user channel_id: str - ID of the channel actions: list - list of actions for example: ["m_write", "m_read"] token: str - token used for sharing thing + + + +**returns:** + + - `mf_resp`: "OK" + +Usage: +``` + + >>> from mainflux import sdk >>> mfsdk = sdk.SDK(things_url="http://localhost:9000") >>> user_id = "fd4f7da5-b7bf-49b7-bf2f-99995e78afd9" >>> channel_id = "567f7da5-b7bf-49b7-bf2f-99995e78afd9" >>> actions = ["m_write", "m_read"] >>> mf_resp = mfsdk.things.share_thing(user_id, channel_id, actions) >>> mf_resp --- - + ### method `update` @@ -187,11 +360,24 @@ Share thing update(thing_id: str, thing: dict, token: str) ``` -Updates thing entity +Updates thing entity. + +Allows a logged in user to make changes and update a thing's information with provided thing ID and valid token. Information such as the metadata and name can be updated. + +params: thing_id: str - ID of the thing thing: dict - thing information for example: { "name": "thing1" } token: str - token used for updating thing information + + + +**returns:** + + - `mf_resp`: response.Response - response object. + +Usage: +``` >>> from mainflux import sdk >>> mfsdk = sdk.SDK(things_url="http://localhost:9000") >>> thing_id = "fd4f7da5-b7bf-49b7-bf2f-99995e78afd9" >>> thing = { ... "name": "thing2", ... } >>> mf_resp = mfsdk.things.update(thing_id, thing) >>> mf_resp --- - + ### method `update_thing_owner` @@ -199,11 +385,26 @@ Updates thing entity update_thing_owner(thing_id: str, thing: dict, token: str) ``` -Updates thing secret +Updates thing owner. + +Allows a logged in user to make changes and update a thing's information with provided thing ID and valid token. The thing owner can be updated. + +params: thing_id: str - ID of the thing thing: dict - thing information for example: { "owner": "user1" } token: str - token used for updating thing information + + + +**returns:** + + - `mf_resp`: response.Response - response object. + +Usage: +``` + + >>> from mainflux import sdk >>> mfsdk = sdk.SDK(things_url="http://localhost:9000") >>> thing_id = "fd4f7da5-b7bf-49b7-bf2f-99995e78afd9" >>> thing = { ... "owner": "user1" ... } >>> mf_resp = mfsdk.things.update_thing_owner(thing_id, thing) >>> mf_resp --- - + ### method `update_thing_secret` @@ -211,11 +412,26 @@ Updates thing secret update_thing_secret(thing_id: str, thing: dict, token: str) ``` -Updates thing secret +Updates thing secret. + +Allows a logged in user to make changes and update a thing's information with provided thing ID and valid token. The thing's secret can be updated. + +params: thing_id: str - ID of the thing thing: dict - thing information for example: { "key": "thing1" } token: str - token used for updating thing information + + + +**returns:** + + - `mf_resp`: response.Response - response object. + +Usage: +``` + + >>> from mainflux import sdk >>> mfsdk = sdk.SDK(things_url="http://localhost:9000") >>> thing_id = "fd4f7da5-b7bf-49b7-bf2f-99995e78afd9" >>> thing = { ... "key": "thing2", ... } >>> mf_resp = mfsdk.things.update_thing_secret(thing_id, thing) >>> mf_resp --- - + ### method `update_thing_tags` @@ -223,7 +439,22 @@ Updates thing secret update_thing_tags(thing_id: str, thing: dict, token: str) ``` -Updates thing secret +Updates thing tags. + +Allows a logged in user to make changes and update a thing's information with provided thing ID and valid token. The thing's tags can be updated. + +params: thing_id: str - ID of the thing thing: dict - thing information for example: { "tags": ["tag1", "tag2"] } token: str - token used for updating thing information + + + +**returns:** + + - `mf_resp`: response.Response - response object. + +Usage: +``` + + >>> from mainflux import sdk >>> mfsdk = sdk.SDK(things_url="http://localhost:9000") >>> thing_id = "fd4f7da5-b7bf-49b7-bf2f-99995e78afd9" >>> thing = { ... "tags": ["tag1", "tag2"] ... } >>> mf_resp = mfsdk.things.update_thing_tags(thing_id, thing) >>> mf_resp diff --git a/mainflux/things.py b/mainflux/things.py index 2c6eb24..024dd59 100644 --- a/mainflux/things.py +++ b/mainflux/things.py @@ -32,7 +32,7 @@ def __init__(self, url: str): None """ def create(self, thing: dict, token: str): - """Creates thing entity in the databas + """Creates thing entity in the database. Creates a new thing with provided thing information. If token is provided, it will be used to create a new thing @@ -72,7 +72,7 @@ def create(self, thing: dict, token: str): mf_resp.value = http_resp.json() return mf_resp - def create_bulk(self, things: list, token: str) + def create_bulk(self, things: list, token: str): """Creates multiple things in bulk. Creates multiple new things with provided things information. @@ -118,7 +118,7 @@ def create_bulk(self, things: list, token: str) return mf_resp def get(self, thing_id: str, token: str): - """Gets a thing entity for a logged-in user + """Gets a thing entity. Provides information about a thing with provided thing ID and token. Information about a thing is provided in a JSON format and includes the name @@ -244,7 +244,7 @@ def get_by_channel(self, channel_id: str, query_params: dict, token: str): return mf_resp def update(self, thing_id: str, thing: dict, token: str): - """Updates thing entity + """Updates thing entity. Allows a logged in user to make changes and update a thing's information with provided thing ID and valid token. Information @@ -288,7 +288,7 @@ def update(self, thing_id: str, thing: dict, token: str): return mf_resp def update_thing_secret(self, thing_id: str, thing: dict, token: str): - """Updates thing secret + """Updates thing secret. Allows a logged in user to make changes and update a thing's information with provided thing ID and valid token. The thing's @@ -332,7 +332,7 @@ def update_thing_secret(self, thing_id: str, thing: dict, token: str): return mf_resp def update_thing_tags(self, thing_id: str, thing: dict, token: str): - """Updates thing tags + """Updates thing tags. Allows a logged in user to make changes and update a thing's information with provided thing ID and valid token. The thing's @@ -376,7 +376,7 @@ def update_thing_tags(self, thing_id: str, thing: dict, token: str): return mf_resp def update_thing_owner(self, thing_id: str, thing: dict, token: str): - """Updates thing owner + """Updates thing owner. Allows a logged in user to make changes and update a thing's information with provided thing ID and valid token. The thing @@ -420,7 +420,7 @@ def update_thing_owner(self, thing_id: str, thing: dict, token: str): return mf_resp def disable(self, thing_id: str, token: str): - """Deletes a thing entity from database. + """Deletes a thing entity from the database. Deletes a thing with provided thing ID and valid token. @@ -452,7 +452,7 @@ def disable(self, thing_id: str, token: str): return mf_resp def connects(self, thing_ids: list, channel_ids: list, actions: list, token: str): - """Connects thing and channel. + """Connects things and channels. Connects multiple things and channels with provided thing IDs as the subjects, channel IDs as the objects, actions that the @@ -495,7 +495,7 @@ def connects(self, thing_ids: list, channel_ids: list, actions: list, token: str return mf_resp def disconnects(self, thing_ids: list, channel_ids: list, token: str): - """Disconnect thing and channel + """Disconnect things and channels. Disconnects multiple things and channels with provided thing IDs as the subjects, channel IDs as the objects and a valid token. @@ -532,7 +532,7 @@ def disconnects(self, thing_ids: list, channel_ids: list, token: str): return mf_resp def connect(self, thing_id: str, channel_id: str, action: str, token: str): - """Connects thing and channel + """Connects thing and channel. Connects a thing and channel with provided thing ID as the subject, channel ID as the object, action that the thing can partake in and a @@ -574,7 +574,7 @@ def connect(self, thing_id: str, channel_id: str, action: str, token: str): return mf_resp def disconnect(self, thing_id: str, channel_id: str, token: str): - """Disconnect thing and channel + """Disconnects thing and channel. Disconnects a thing and channel with provided thing ID as the subject, channel ID as the object and a valid token. @@ -611,7 +611,7 @@ def disconnect(self, thing_id: str, channel_id: str, token: str): return mf_resp def share_thing(self, user_id: str, channel_id: str, actions: list, token: str): - """Share thing + """Shares thing. Allows a logged in user to create new policies for a thing over a channel provided with a user ID, channel ID, actions that the thing can partake in @@ -654,7 +654,7 @@ def share_thing(self, user_id: str, channel_id: str, actions: list, token: str): return mf_resp def authorise_thing(self,access_request: dict, token: str): - """Authorises thing + """Authorises thing. Creates policies for a thing as a subject over a channel which is the object. It authorizes the thing to perform some actions over the channel.