Optional parameters

core/imageroot/usr/local/agent/pypkg/agent/__init__.py

@@ -608,17 +608,21 @@ def get_bound_domain_list(rdb, module_id=None):
     else:
         return []
 
-def allocate_ports(ports_number: int, module_id: str, protocol: str):
+def allocate_ports(ports_number: int, protocol: str, module_id: str=""):
     """
     Allocate a range of ports for a given module,
     if it is already allocated it is deallocated first.
 
     :param ports_number: Number of consecutive ports required.
-    :param module_id: Name of the module requesting the ports.
     :param protocol: Protocol type ('tcp' or 'udp').
+    :param module_id: Name of the module requesting the ports.
+                      Parameter is optional, if not provided, default value is environment variable MODULE_ID.
     :return: A tuple (start_port, end_port) if allocation is successful, None otherwise.
     """
 
+    if module_id == "":
+        module_id = os.environ['MODULE_ID']
+
     node_id = os.environ['NODE_ID']
     response = agent.tasks.run(
         agent_id=f'node/{node_id}',
@@ -636,15 +640,19 @@ def allocate_ports(ports_number: int, module_id: str, protocol: str):
     return response['output']
 
 
-def deallocate_ports(module_id: str, protocol: str):
+def deallocate_ports(protocol: str, module_id: str=""):
     """
     Deallocate the ports for a given module.
 
-    :param module_id: Name of the module whose ports are to be deallocated.
     :param protocol: Protocol type ('tcp' or 'udp').
+    :param module_id: Name of the module whose ports are to be deallocated.
+                      Parameter is optional, if not provided, default value is environment variable MODULE_ID.
     :return: A tuple (start_port, end_port) if deallocation is successful, None otherwise.
     """
 
+    if module_id == "":
+        module_id = os.environ['MODULE_ID']
+
     node_id = os.environ['NODE_ID']
     response = agent.tasks.run(
         agent_id=f'node/{node_id}',

docs/core/port_allocation.md

@@ -24,6 +24,8 @@ This function allows you to allocate a specific number of ports for a given modu
   - `module_name` (*str*): The name of the module requesting the ports.
   - `protocol` (*str*): The protocol for which the ports are required (e.g. "tcp" or "udp").
 
+- **Return** a tuple (start_port, end_port) if allocation is successful, `None` otherwise.
+
 - **Usage Example**:
 
 ```python
@@ -39,6 +41,8 @@ This function allows you to deallocate all ports previously assigned to a specif
   - `module_name` (*str*): The name of the module for which ports should be deallocated.
   - `protocol` (*str*): The protocol for which the ports were allocated (e.g., "tcp" or "udp").
 
+- **Return** a tuple (start_port, end_port) if deallocation is successful, `None` otherwise.
+
 - **Usage Example**:
 
 ```python

docs/modules/port_allocation.md

@@ -30,7 +30,7 @@ Currently, allocated ports are saved in an SQLite database file managed by the l
 
 The Python `agent` library provides a convenient interface for managing port allocation and deallocation, based on the node actions `allocate_ports` and `deallocate_ports`.
 
-It is recommended to use `os.environ['MODULE_ID']` to ensure the correct module name is used, as calling the function with a name that does not correspond to the invoking module will result in an exception.
+It is optional to specify the `module_id` when calling the port allocation or deallocation functions. By default, if the `module_id` is not provided, the function will automatically use the value of the `MODULE_ID` environment variable. This simplifies the function calls in common scenarios, ensuring the correct module name is used without manual input. However, if needed, you can still explicitly pass the `module_id`.
 
 ### Allocate ports
 
@@ -39,25 +39,27 @@ Imagine an application module that initially requires only one TCP port. Later,
 If ports are already allocated for this module, the previous allocation will be deallocated, and the new requested range of ports will be allocated. Here’s how this can be done:
 
 ```python
-import agent
-import os
-
-# Allocate 4 TCP ports for the "my_module" module
-allocated_ports = agent.allocate_ports(4, os.environ['MODULE_ID'], "tcp")
-print(f"Allocated TCP ports: {allocated_ports}")
+# Allocate 4 TCP ports for the module that is calling the function
+allocated_ports = agent.allocate_ports(4, "tcp")
+```
+or
+```python
+# Allocate 4 UDP ports for "my_module" module
+allocated_ports = agent.allocate_ports(4, "udp", "my_module")
 ```
 
 ### Deallocate ports
 
 If the module no longer needs the allocated ports, such as when a feature is removed or disabled, the ports can be easily deallocated:
 
 ```python
-import agent
-import os
-
+# Deallocate TCP ports for the module that is calling the function
+deallocated_ports = agent.deallocate_ports("tcp")
+```
+or
+```python
 # Deallocate UDP ports for the "my_module" module
-deallocated_ports = agent.deallocate_ports(os.environ['MODULE_ID'], "udp")
-print(f"Deallocated UDP ports: {deallocated_ports}")
+deallocated_ports = agent.deallocate_ports("udp", "my_module")
 ```
 By deallocating the ports, the module frees up the resources, allowing other modules to use those ports.