Merge branch 'development' into dependabot/pip/development/virtualenv-20.24.1

Author: Th3Un1q3

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.3.1
+current_version = 0.3.4
 commit = False
 tag = False
 

.github/workflows/bump-version.yml

@@ -22,7 +22,7 @@ jobs:
           access_token: ${{ github.token }}
 
 
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           token: ${{ secrets.EMNIFY_GITHUB_ACTIONS_TOKEN }}
 

.github/workflows/documentation.yml

@@ -17,7 +17,7 @@ jobs:
         with:
           access_token: ${{ github.token }}
 
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Prepare doc-gen
         run: docker build . -f docs/Dockerfile.dev -t emnify/python-sdk-docs

.github/workflows/gitleaks.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: gitleaks
         uses: zricethezav/[email protected]
         with:

.github/workflows/unit-tests.yml

@@ -18,7 +18,7 @@ jobs:
         uses: styfle/[email protected]
         with:
           access_token: ${{ github.token }}
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Install dependencies
         run: pip install -r req.txt

DEVELOPMENT.md

@@ -24,7 +24,7 @@ To set up your sandbox, modify the code in this file as needed.
 
 Once your sandbox is set up, you can launch the file and view the results.
 ```shell
-docker run -t -e EMNIFY_APPLICATION_TOKEN=<your_token_here> -v $(pwd):/sdk emnify/python-sdk python docs/examples/local_debug.py
+docker run -t -e EMNIFY_SDK_APPLICATION_TOKEN=<your_token_here> -e EMINFY_SDK_API_ENDPOINT_URL=<your_debug_API_endpoint> -v $(pwd):/sdk emnify/python-sdk python docs/examples/local_debug.py
 ```
 
 ## Version Bump

Pipfile

@@ -10,7 +10,7 @@ distlib = "==0.3.6"
 filelock = "==3.12.2"
 idna = "==3.4"
 importlib-metadata = "==6.7.0"
-pipenv = "==2023.6.18"
+pipenv = "==2023.7.23"
 platformdirs = "==3.5.1"
 pydantic = "==1.10.9"
 requests = "==2.31.0"

docs/examples/device_lifecycle_management.py

@@ -1,21 +1,27 @@
+# === Example: Initialize the SDK client ===
+
 from emnify import EMnify
 from emnify import constants as emnify_constants
 
-emnify = EMnify(app_token='your token')
+# To operate the emnify SDK, you need to generate an application token.
+# Step-by-step guide: https://www.emnify.com/developer-blog/how-to-use-an-application-token-for-api-authentication
+emnify = EMnify(app_token='YOUR_TOKEN')
+
 # [endblock]
-#  === Create and activate a device ===
 
+# === Example: Create and activate a device ===
 
 unassigned_sims = [i for i in emnify.sim.get_sim_list(without_device=True)]
-#  If no unassigned_sims - register new one by batch code
+#  If there aren't any unassigned SIMs, register a new one via batch code:
 if not unassigned_sims:
-    registered_sim = emnify.sim.register_sim(bic='sample_bic_code')  # Returns as list
+    registered_sim = emnify.sim.register_sim(bic='EXAMPLE_BIC_CODE') # Returns a list
     sim = emnify.sim.retrieve_sim(registered_sim[0].id)
 else:
-    sim = unassigned_sims[0]  # Taking the first one unassigned sim
+    sim = unassigned_sims[0]  # Takes the first unassigned SIM
 
-# Defining of new device parameters
-# All required models can be retrieved through manager`s properties
+# To create your new device, you need to define the parameters.
+# You can retrieve all required models through the manager properties.
+# API reference: https://emnify.github.io/emnify-sdk-python/autoapi/emnify/modules/device/manager/index.html
 service_profile = emnify.devices.service_profile_model(id=1)
 tariff_profile = emnify.devices.tariff_profile_model(id=1)
 device_status = emnify.devices.status_model(id=0)
@@ -28,50 +34,51 @@
     name=name
 )
 
-# After creating model sdk returns id of device
+# After creating a model, the SDK returns the device ID.
 device_id = emnify.devices.create_device(device=device_model)
-# Then we can retrieve all device details
+# Then, you can retrieve the device details
 device = emnify.devices.retrieve_device(device_id=device_id)
-# Activate device
+# and finally, activate the device:
 emnify.devices.change_status(device=device, enable=True)
 
-# Retrieving updated device details
+# Retrieve updated device details
 device = emnify.devices.retrieve_device(device_id=device_id)
-device_status = device.status.description  # Will be 'Enabled'
-sim_status = device.sim.status.description  # Will be 'Activated'
+device_status = device.status.description  # Device status is "Enabled"
+sim_status = device.sim.status.description  # SIM status is "Activated"
+
 # [endblock]
 
-#  === Configure a device ===
+# === Example: Configure a device ===
 
-#  Getting details of device
+# Get device details
 device = emnify.devices.retrieve_device(device_id=device_id)
 
-tags = 'arduino, meter, temp'  # Sample tags
-name = 'new name'  # Sample name
+tags = 'arduino, meter, temp'  # Example tags
+name = 'new name'  # Example name
 
-# Adjust device config
+# Adjust the device configuration
 update_device_fields = emnify.devices.device_update_model(name='new name', tags='arduino')
 emnify.devices.update_device(device_id=device.id, device=update_device_fields)
 
-#  Getting details of updated device
+# Get updated device details
 updated_device = emnify.devices.retrieve_device(device_id=device_id)
-device_tags = updated_device.tags  # Will be arduino
-deivce_name = updated_device.name  # Will be 'new name'
+device_tags = updated_device.tags  # Updated tag is "arduino"
+deivce_name = updated_device.name  # Updated name is "new name"
 # [endblock]
 
-#  === Configure operator blacklist for device ===
+# === Example: Configure operator blacklist for a device ===
 
-# List of all operators
+# Retrieve a list of all operators
 all_operators = [i for i in emnify.operator.get_operators()]
 
-device_id = 0  # Your device id
+# Add three operators to the blacklist:
+device_id = 0  # Your device ID
 emnify.devices.add_device_blacklist_operator(operator_id=all_operators[0].id, device_id=device_id)
 emnify.devices.add_device_blacklist_operator(operator_id=all_operators[1].id, device_id=device_id)
 emnify.devices.add_device_blacklist_operator(operator_id=all_operators[2].id, device_id=device_id)
-# Adding 3 operators to the blacklist
 
+# Get all blacklist operators of the device by device ID:
 device_blacklist = emnify.devices.get_device_operator_blacklist(device_id=device_id)
-# Getting all blacklist operators of device by device_id
 
 operator_id = 0
 for operator in device_blacklist:
@@ -80,78 +87,76 @@
     print(operator.mnc)
     operator_id = operator.id
 
+# Removes the last operator from the blacklist
 emnify.devices.delete_device_blacklist_operator(device_id=device_id, operator_id=operator_id)
-# Removing the last operator from blacklist
+
 # [endblock]
 
-#  === Disable device ===
+# === Example: Disable a device ===
 
+# Get a list of all devices with SIM cards and the "Enabled" device status
 device_filter = emnify.devices.get_device_filter_model(status=emnify_constants.DeviceStatuses.ENABLED_ID.value)
 all_devices_with_sim = [
     device for device in emnify.devices.get_devices_list(filter_model=device_filter) if device.sim
 ]
-# Getting list of all devices with sim cards and enabled status
 
 device = all_devices_with_sim[0]
 
-emnify.devices.change_status(disable=True, device=device.id)
 # Disable a device
+emnify.devices.change_status(disable=True, device=device.id)
 
 disabled_device = emnify.devices.retrieve_device(device_id=device.id)
-device_status = disabled_device.status.description  # Will be 'Disabled'
-sim_status = disabled_device.sim.status.description # Will be 'Suspended'
+device_status = disabled_device.status.description  # Device status is "Disabled"
+sim_status = disabled_device.sim.status.description # SIM status is "Suspended"
+
 # [endblock]
 
-#  === Delete device ===
+# === Example: Delete a device ===
 
+# Get a list of all devices
 old_devices_list = [device for device in emnify.devices.get_devices_list()]
-# Getting list of all devices
 
 device_to_delete = list(
         filter(
             lambda device: device.sim and device.status.id == emnify_constants.DeviceStatuses.ENABLED_ID,
             old_devices_list
         )
 )[0]
-# Picking up a device to delete with assigned sim and enabled status
 
+# Choose a device to delete with an assigned SIM and the "Enabled" device status
 sim_id_of_deleted_device = device_to_delete.sim.id
 
+# Delete the device
 emnify.devices.delete_device(device_id=device_to_delete.id)
-# Deleting a device
 
+# Retrieve a new list of all devices
 new_device_list = [device for device in emnify.devices.get_devices_list()]
-# Getting new list of all devices
-
 
+# Once your device is deleted, the total device count should be lower:
 assert len(old_devices_list) > len(new_device_list)
-# After deleting count of all devices will be lowered
 
 sim = emnify.sim.retrieve_sim(sim_id=sim_id_of_deleted_device)
-sim_status = sim.status.description  # Will be 'Suspended'
+sim_status = sim.status.description  # SIM status is 'Suspended'
 
 # [endblock]
 
+# === Example: Manage device connectivity ===
 
-#  === Manage device connectivity ===
-
-# Lookup for documentation for learn more
-# https://www.emnify.com/developer-blog/5-ways-to-detect-and-solve-connectivity-issues#network-events
-
-# There are many reasons why connection issues arise. For example:
-# * The device executes the wrong procedures due to a bad firmware update.
-# * The device executes network registration too frequently that the network no longer allows it to register.
-# * You have simply changed a policy due to a blocked device.
+# There are many reasons why connection issues arise. 
+# For example:
+# - The device executes the wrong procedures due to a bad firmware update.
+# - The device executes network registration too frequently, so the network no longer allows it to register.
+# - You changed a policy due to a blocked device.
 
-# For resetting a device connectivity you can use the following methods:
-# * Resetting the connectivity of device
+# To reset device connectivity, use the following methods: 
+# - Reset the device's connectivity
 device_id = 0
 emnify.devices.reset_connectivity_data(device_id=device_id)
-# * Resetting the connectivity
+# - Reset the network connectivity
 emnify.devices.reset_connectivity_network(device_id=device_id)
 
-# For checking connectivity you can use the method:
+# Use the following method to check the connectivity:
 connectivity = emnify.devices.get_device_connectivity_status(device_id=device_id)
-print(connectivity.status.description)  # Will be 'ATTACHED'/'ONLINE'/'OFFLINE'/'BLOCKED'
+print(connectivity.status.description)  # Status is either "Attached", "Online", "Offline", or "Blocked"
 
 # [endblock]

docs/examples/filtering_and_sorting.py

@@ -1,51 +1,58 @@
 
-# === Using a Filtering for List calls  ===
 from emnify import EMnify
 from emnify import constants as emnify_constants
 
-emnify_client = EMnify(app_token='your_application_token')
+# To operate the emnify SDK, you need to generate an application token.
+# Step-by-step guide: https://www.emnify.com/developer-blog/how-to-use-an-application-token-for-api-authentication
+emnify_client = EMnify(app_token='YOUR_TOKEN')
 
 # Some methods that return multiple objects allow sorting and filtering.
-# This allows us to optimize processing time, since using filtering we can immediately get the necessary objects with
-# the necessary qualities, and sorting allows us to set the order in which objects are displayed.
-# Instead of sending several requests in search of the required object, we can reduce their number to one.
+# API reference: https://emnify.github.io/emnify-sdk-python/autoapi/index.html
 
-# For example - we want to find all SIM`s with specific customer organisation, first one for instance.
-# We need to initiate the model for filtering by specifying the necessary parameters in it as arguments.
+# This optimizes processing time because:
+# - Filtering lets you only retrieve the objects you need.
+# - Sorting allows you to set the order that objects are displayed.
+# Instead of sending several requests to get the required object, you only need one.
+
+# === Example: Filter a list of SIM cards ===
+
+# This example finds all SIMs for a specific customer organization.
+# Start by initiating the model for filtering by specifying the necessary parameters as arguments.
 sim_filter = emnify_client.sim.get_sim_filter_model(customer_org=1)
-# To get the filtering model for filling, you need to get it as a property of a manager
-# for SIM cards, this would be get_sim_filter_model, for Devices it would be a get_device_filter_model
 
-# After initializing the model object, it must be passed as an argument that makes a request to get a list of objects.
+# Next, you need to get the filtering model for filling as a property of a manager.
+# For SIM cards: get_sim_filter_model
+# For devices: get_device_filter_model
+
+# After initializing the model object, pass it as an argument to request a list of objects.
 sims = emnify_client.sim.get_sim_list(filter_model=sim_filter)
-# sims now contains the objects we need with client organization 1
+# Now, sims contains the objects for customer organization 1.
 
-# We can pass several parameters for filtering for a more detailed search for the necessary objects.
+# For a more detailed search, pass several parameters for filtering:
 sim_filter = emnify_client.sim.get_sim_filter_model(
     customer_org=1,
     status=emnify_constants.SimStatusesID.ACTIVATED_ID.value,
     production_date='2019-01-25'
 )
 
-# The request to get a list of SIM cards also has a separate filter,
-# which is passed as an argument to the filtering function - without a device.
-
+# The list SIM cards request also has a separate filter, passed as an argument.
+# The following example searches for SIMs without a device:
 sims_without_assigned_device = emnify_client.sim.get_sim_list(without_device=True)
 
+# === Example: Sort all devices ===
 
-# === Using a Sorting for List calls  ===
-# Just like filtering, sorting allows us to reduce processing time by ordering objects in the server.
-# Thus, it is easier for you to group objects according to a certain attribute by specifying it in sorting.
+# Like filtering, sorting reduces processing time by ordering objects in the server.
+# Sorting also enables you to group objects by specifying a particular attribute.
 
-# For example - we want to get all devices sorted by last updated date
-# All sorting is done by using enums
+# The following example sorts all devices by the last updated date.
+# Note: All sorting uses enums.
 sort_parameter = emnify_client.devices.get_device_sort_enum.LAST_UPDATED.value
 
-# After choosing a parameter for filtering, we need to pass it as an argument sort_enum
+# After choosing a filtering parameter, pass it as an argument to sort_enum:
 sorted_devices = emnify_client.devices.get_devices_list(
     sort_enum=sort_parameter
 )
 
-# Now we got a list of devices, at the beginning of which are the recently updated devices
+# Now, you have a list of devices with the most recently updated at the top.
 for latest_device in sorted_devices:
     ...

docs/examples/local_debug.py

@@ -10,13 +10,38 @@
 from emnify import EMnify
 
 # Get the token from environment variable
-TOKEN = os.environ.get('EMNIFY_APPLICATION_TOKEN')
+TOKEN = os.environ.get('EMNIFY_SDK_APPLICATION_TOKEN')
 
 # Initiate SDK instance using application token
 emnify = EMnify(TOKEN)
 
+def get_iterator_length(iterator):
+    return len(list(iterator))
+
 # Execute a command against desired API
 devices = emnify.devices.get_devices_list()
+#
+#
+## print first 100 devices
+for i, device in enumerate(devices):
+    if i >= 100:
+        break
+    print(device)
+
+# Count remaining devices
+print(get_iterator_length(devices))
+
+
+# Get list of sims
+sims = emnify.sim.get_sim_list()
+
+# Count sims
+print(get_iterator_length(sims))
+
+sms_list = emnify.devices.get_device_sms_list(device=11379224)
+print(list(sms_list))
+print(sms_list)
 
-# Showing all the devices
-print([device for device in devices])
+# Get list of events
+events = emnify.devices.get_device_events_list(device=11379224)
+print(list(events))