Develop

README.rst

@@ -116,4 +116,20 @@ Note about types of times and binaryData
 1. All times: **DatetimeWithNanoseconds** (defined in the **proto.datetime_helpers** module)
 2. All **binaryData** (CONFIG, STATE etc.): **BYTE ARRAYS**
 
-- If this environment variable is not set, or is set to any unexpeced values, then the default types listed previously are used.
+- If this environment variable is not set, or is set to any unexpeced values, then the default types listed previously are used.
+
+Note about running from source instead of PyPi (pip) module:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+- To temporarily use the source code in this repo. instead of the installed PyPi (pip) module do the following:
+
+1. Clone this repo.
+2. Checkout the desired branch using **git checkout <branch>**.
+3. In your code find where **clearblade** or **clearblade.cloud** is being imported.
+4. Precede that line with **import sys** and **sys.path.insert(0, <path_to_python-iot>)**. The path must end with "python-iot". So for example:
+
+.. code-block:: console
+
+    import sys
+    sys.path.insert(0, "path/to/python-iot")
+
+    from clearblade.cloud import iot_v1

UPGRADING.md

@@ -1,157 +1,151 @@
-# 2.0.0 Migration Guide
-
-The 2.0 release of the `google-cloud-iot` client is a significant upgrade based on a [next-gen code generator](https://github.com/googleapis/gapic-generator-python), and includes substantial interface changes. Existing code written for earlier versions of this library will likely require updates to use this version. This document describes the changes that have been made, and what you need to do to update your usage.
-
-If you experience issues or have questions, please file an [issue](https://github.com/googleapis/python-iot/issues).
-
-## Supported Python Versions
-
-> **WARNING**: Breaking change
-
-The 2.0.0 release requires Python 3.6+.
-
+<!-- "Copyright 2023 ClearBlade Inc."
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+https://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+Copyright 2018 Google LLC
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+https://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+Copyright 2023 ClearBlade Inc.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+https://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+Copyright 2018 Google LLC
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+https://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License. -->
 
-## Method Calls
-
-> **WARNING**: Breaking change
-
-Methods expect request objects. We provide a script that will convert most common use cases.
-
-* Install the library with `libcst`.
-
-```py
-python3 -m pip install google-cloud-iot[libcst]
-```
-
-* The script `fixup_iot_v1_keywords.py` is shipped with the library. It expects
-an input directory (with the code to convert) and an empty destination directory.
+# 2.0.0 Migration Guide
 
-```sh
-$ fixup_iot_v1_keywords.py --input-directory .samples/ --output-directory samples/
-```
+The 2.0 release of the `clearblade-cloud-iot` client is a significant upgrade based on addition of two new classes in **iot_v1**:
 
-**Before:**
-```py
-from google.cloud import iot_v1
+- **DeviceCredential**
+- **PublicKeyCredential**
 
-client = iot_v1.DeviceManagerClient()
+The release also includes enhancements to these classes already present in **iot_v1**:
 
-registry = client.get_device_registry("registry_name")
-```
+- **DeviceConfig**
+- **DeviceState**
 
+The version was made with the intent of minimizing required code changes. **However these changes should be considrered Breaking changes**.
 
-**After:**
-```py
-from google.cloud import iot_v1
+#
 
-client = iot_v1.DeviceManagerClient()
+1. If **device** is an object of class **Device**.
 
-registry = client.get_device_registry(request={'name': "registry_name"})
-```
+   **Before**:
+   device.credentials is of type **[dict]** (i.e. list of dicts).
 
-### More Details
+   **After**:
+   device.credentials is of type **[DeviceCredential]** (i.e. list of objects of class DeviceCredential).
 
-In `google-cloud-iot<2.0.0`, parameters required by the API were positional parameters and optional parameters were keyword parameters.
+   The **DeviceCredential** class has these features for usability:
 
-**Before:**
-```py
-    def create_device(
-        self,
-        parent,
-        device,
-        retry=google.api_core.gapic_v1.method.DEFAULT,
-        timeout=google.api_core.gapic_v1.method.DEFAULT,
-        metadata=None,
-    ):
-```
+   - A **get** method that mimics the **get** method of a dict.
+   - Allows accessing attributes using dot notation OR square-brackets.
+   - Supports camel-case as well as snake-case for accessing attributes:
 
-In the 2.0.0 release, all methods have a single positional parameter `request`. Method docstrings indicate whether a parameter is required or optional.
+   e.g. All these are valid for retrieving the public key:
 
-Some methods have additional keyword only parameters. The available parameters depend on the `google.api.method_signature` annotation specified by the API producer.
+   - **public_key = device.credentials[0]['publicKey']**
+   - **public_key = device.credentials[0]['public_key']**
+   - **public_key = device.credentials[0].get('publicKey')**
+   - **public_key = device.credentials[0].get('public_key')**
+   - **public_key = device.credentials[0].publicKey**
+   - **public_key = device.credentials[0].public_key**
 
+#
 
-**After:**
-```py
-    def create_device(
-        self,
-        request: device_manager.CreateDeviceRequest = None,
-        *,
-        parent: str = None,
-        device: resources.Device = None,
-        retry: retries.Retry = gapic_v1.method.DEFAULT,
-        timeout: float = None,
-        metadata: Sequence[Tuple[str, str]] = (),
-    ) -> resources.Device:
-```
+2. This refers to pub_key mentioned in the previous section.
 
-> **NOTE:** The `request` parameter and flattened keyword parameters for the API are mutually exclusive.
-> Passing both will result in an error.
+   **Before**:
+   public_key was of type **dict**.
 
+   **After**:
+   public_key is an object of class **PublicKeyCredential**.
 
-Both of these calls are valid:
+   The **PublicKeyCredential** class has these features for usability:
 
-```py
-response = client.create_device(
-    request={
-        "parent": parent,
-        "device": device,
-    }
-)
-```
+   - A **get** method that mimics the **get** method of a dict.
+   - Allows accessing attributes using dot notation OR square-brackets.
 
-```py
-response = client.create_device(
-    parent=parent,
-    device=device,
-)
-```
+   e.g. All these are valid for retrieving the public key format:
 
-This call is invalid because it mixes `request` with a keyword argument `device`. Executing this code
-will result in an error.
+   - **format = public_key['format']**
+   - **format = public_key.get('format')**
+   - **format = public_key.format**
 
-```py
-response = client.create_device(
-    request={
-        "parent": parent,
-    },
-    device=device
-)
-```
+#
 
+3. This section refers to **dev_config** which holds device config.
 
+   **Before**:
+   dev_config is of type **dict**.
 
-## Enums and Types
+   **After**:
+   dev_config is an object of class **DeviceConfig**.
 
+   The **DeviceConfig** class has these features for usability:
 
-> **WARNING**: Breaking change
+   - A **get** method that mimics the **get** method of a dict.
+   - Allows accessing attributes using dot notation OR square-brackets.
+   - Supports camel-case as well as snake-case for accessing attributes:
 
-The submodules `enums` and `types` have been removed.
+   e.g. All these are valid for retrieving the cloud_update_time:
 
-**Before:**
-```py
-from google.cloud import iot_v1
+   - **cloud_update_time = device.credentials[0]['cloudUpdateTime']**
+   - **cloud_update_time = device.credentials[0]['cloud_update_time']**
+   - **cloud_update_time = device.credentials[0].get('cloudUpdateTime')**
+   - **cloud_update_time = device.credentials[0].get('cloud_update_time')**
+   - **cloud_update_time = device.credentials[0].cloudUpdateTime**
+   - **cloud_update_time = device.credentials[0].cloud_update_time**
 
-gateway_type = iot_v1.enums.GatewayType.GATEWAY
-device = iot_v1.types.Device(name="name")
-```
+#
 
+4. This section refers to **dev_state** which contains device state.
 
-**After:**
-```py
-from google.cloud import iot_v1
+   **Before**:
+   dev_state is of type **dict**.
 
-gateway_type = iot_v1.GatewayType.GATEWAY
-device = iot_v1.Device(name="name")
-```
+   **After**:
+   dev_state is an object of class **DeviceState**.
 
-## Location Path Helper Method
+   The **DeviceState** class has these features for usability:
 
-Location path helper method has been removed. Please construct
-the path manually.
+   - A **get** method that mimics the **get** method of a dict.
+   - Allows accessing attributes using dot notation OR square-brackets.
+   - Supports camel-case as well as snake-case for accessing attributes:
 
-```py
-project = 'my-project'
-location = 'location'
+   e.g. All these are valid for retrieving the binary_data:
 
-location_path = f'projects/{project}/locations/{location}'
-```
+   - **binary_data = device.credentials[0]['binaryData']**
+   - **binary_data = device.credentials[0]['binary_data']**
+   - **binary_data = device.credentials[0].get('binaryData')**
+   - **binary_data = device.credentials[0].get('binary_data')**
+   - **binary_data = device.credentials[0].binaryData**
+   - **binary_data = device.credentials[0].binary_data**

clearblade/cloud/iot_v1/__init__.py

@@ -1,3 +1,47 @@
+"""
+"Copyright 2023 ClearBlade Inc."
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+https://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+Copyright 2018 Google LLC
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+https://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+Copyright 2023 ClearBlade Inc.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+https://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+Copyright 2018 Google LLC
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+https://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
 from .client import DeviceManagerClient, DeviceManagerAsyncClient
 from .device_types import *
 from .registry_types import *

clearblade/cloud/iot_v1/client.py

@@ -1,3 +1,47 @@
+"""
+"Copyright 2023 ClearBlade Inc."
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+https://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+Copyright 2018 Google LLC
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+https://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+Copyright 2023 ClearBlade Inc.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+https://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+Copyright 2018 Google LLC
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+https://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
 from .device_types import *
 from .devices import *
 from .registry import *