rccn-gen 1.2.0__py3-none-any.whl → 1.3.1__py3-none-any.whl

rccn_gen/utils.py

@@ -6,6 +6,22 @@ from yamcs.pymdb import IntegerArgument, FloatArgument, BooleanArgument, Enumera
 
 
 def to_upper_camel_case(s):
+    """
+    Convert a string to UpperCamelCase (PascalCase).
+    
+    Converts the first letter to uppercase and capitalizes each word 
+    after spaces or underscores, removing all non-alphanumeric characters.
+    
+    Parameters:
+    -----------
+    s : str
+        The input string to convert.
+        
+    Returns:
+    --------
+    str
+        The converted string in UpperCamelCase.
+    """
     if s[0].islower():
         s = s[0].upper() + s[1:]
     if ' ' in s or '_' in s:
@@ -14,12 +30,48 @@ def to_upper_camel_case(s):
     return s
 
 def to_snake_case(s):
+    """
+    Convert a string to snake_case.
+    
+    Inserts underscores before uppercase letters, converts the string to lowercase,
+    replaces non-alphanumeric characters with underscores, and eliminates consecutive underscores.
+    
+    Parameters:
+    -----------
+    s : str
+        The input string to convert.
+        
+    Returns:
+    --------
+    str
+        The converted string in snake_case.
+    """
     s = re.sub(r'(?<!^)(?=[A-Z])', '_', s).lower()
     s = re.sub(r'[^a-zA-Z0-9_]', '_', s)
     s = re.sub(r'__', '_', s)
     return s
 
 def replace_with_indentation(text, keyword, replacement):
+    """
+    Replace a keyword in text while preserving the original indentation.
+    
+    This function finds the indentation level of the line containing the keyword
+    and applies the same indentation to each line of the replacement text.
+    
+    Parameters:
+    -----------
+    text : str
+        The original text containing the keyword.
+    keyword : str
+        The keyword to replace.
+    replacement : str
+        The replacement text.
+        
+    Returns:
+    --------
+    str
+        The text with the keyword replaced by properly indented replacement text.
+    """
     lines = text.split('\n')
     indent = 0
     for line in lines:
@@ -29,6 +81,26 @@ def replace_with_indentation(text, keyword, replacement):
     return text.replace(keyword, replacement.replace('\n', ('\n'+(indent*' '))))
 
 def insert_before_with_indentation(text, keyword, replacement):
+    """
+    Insert text before a keyword while preserving the original indentation.
+    
+    This function finds the indentation level of the line containing the keyword
+    and applies the same indentation to each line of the text to be inserted.
+    
+    Parameters:
+    -----------
+    text : str
+        The original text containing the keyword.
+    keyword : str
+        The keyword before which to insert text.
+    replacement : str
+        The text to insert before the keyword.
+        
+    Returns:
+    --------
+    str
+        The text with the replacement inserted before the keyword with proper indentation.
+    """
     lines = text.split('\n')
     indent = 0
     for line in lines:
@@ -37,34 +109,146 @@ def insert_before_with_indentation(text, keyword, replacement):
     return text.replace(keyword, (replacement.replace('\n', ('\n'+(indent*' ')))+keyword))
 
 def get_keywords(text):
+    """
+    Extract all keywords from a text.
+    
+    Keywords are identified as text enclosed between double angle brackets.
+    For example: <<KEYWORD>>
+    
+    Parameters:
+    -----------
+    text : str
+        The text to search for keywords.
+        
+    Returns:
+    --------
+    list
+        A list of all keywords found in the text.
+    """
     pattern = r'<<.*?>>'
     return re.findall(pattern, text)
 
 def get_var_keywords(text):
+    """
+    Extract variable keywords from a text.
+    
+    Variable keywords are identified as text starting with <<VAR_ and ending with >>.
+    For example: <<VAR_NAME>>
+    
+    Parameters:
+    -----------
+    text : str
+        The text to search for variable keywords.
+        
+    Returns:
+    --------
+    list
+        A list of all variable keywords found in the text.
+    """
     pattern = r'<<VAR_.*?>>'
     return re.findall(pattern, text)
 
 def get_service_module_keywords(text):
+    """
+    Extract service module keywords from a text.
+    
+    Service module keywords are identified as text starting with <<SERVICE_MODULE_ and ending with >>.
+    For example: <<SERVICE_MODULE_NAME>>
+    
+    Parameters:
+    -----------
+    text : str
+        The text to search for service module keywords.
+        
+    Returns:
+    --------
+    list
+        A list of all service module keywords found in the text.
+    """
     pattern = r'<<SERVICE_MODULE_.*?>>'
     return re.findall(pattern, text)
 
 def get_command_module_keywords(text):
+    """
+    Extract command module keywords from a text.
+    
+    Command module keywords are identified as text starting with <<COMMAND_MODULE_ and ending with >>.
+    For example: <<COMMAND_MODULE_NAME>>
+    
+    Parameters:
+    -----------
+    text : str
+        The text to search for command module keywords.
+        
+    Returns:
+    --------
+    list
+        A list of all command module keywords found in the text.
+    """
     pattern = r'<<COMMAND_MODULE_.*?>>'
     return re.findall(pattern, text)
 
 def delete_all_keywords(text):
-        keywords = get_keywords(text)
-        for keyword in keywords:
-            text = text.replace(keyword, '')
-        return text
+    """
+    Remove all keywords from a text.
+    
+    Finds all text enclosed in double angle brackets and removes them.
+    
+    Parameters:
+    -----------
+    text : str
+        The text containing keywords to be removed.
+        
+    Returns:
+    --------
+    str
+        The text with all keywords removed.
+    """
+    keywords = get_keywords(text)
+    for keyword in keywords:
+        text = text.replace(keyword, '')
+    return text
 
 def delete_all_command_module_keywords(text):
-        keywords = get_command_module_keywords(text)
-        for keyword in keywords:
-            text = text.replace(keyword, '')
-        return text
+    """
+    Remove all command module keywords from a text.
+    
+    Finds all text starting with <<COMMAND_MODULE_ and enclosed in double angle brackets, 
+    then removes them.
+    
+    Parameters:
+    -----------
+    text : str
+        The text containing command module keywords to be removed.
+        
+    Returns:
+    --------
+    str
+        The text with all command module keywords removed.
+    """
+    keywords = get_command_module_keywords(text)
+    for keyword in keywords:
+        text = text.replace(keyword, '')
+    return text
 
 def arg_type_to_rust(arg, bit_number_str='32'):
+    """
+    Convert a pymdb argument type to its corresponding Rust type.
+    
+    Maps different argument types from pymdb to their equivalent Rust data types.
+    
+    Parameters:
+    -----------
+    arg : object
+        A pymdb argument object (IntegerArgument, FloatArgument, etc.)
+    bit_number_str : str, optional
+        Bit width for numeric types. Default is '32'.
+        
+    Returns:
+    --------
+    str
+        The corresponding Rust type name, or None if the type is not supported.
+    """
     if isinstance(arg, IntegerArgument):
         if arg.signed:
             return 'i'+bit_number_str
@@ -83,6 +267,26 @@ def arg_type_to_rust(arg, bit_number_str='32'):
         return None
     
 def arg_enum_rust_definition(arg):
+    """
+    Generate Rust enum definition from an EnumeratedArgument.
+    
+    Creates a Rust enum definition with all choices from the enumerated argument.
+    
+    Parameters:
+    -----------
+    arg : EnumeratedArgument
+        The enumerated argument to convert to a Rust enum definition.
+        
+    Returns:
+    --------
+    str
+        A string containing the complete Rust enum definition.
+        
+    Raises:
+    -------
+    ValueError
+        If the provided argument is not an EnumeratedArgument.
+    """
     if not isinstance(arg, EnumeratedArgument):
         raise ValueError('Provided Argument is not of type EnumeratedArgument.')
     definition_text = 'pub enum '+arg.name+' {\n'
@@ -92,23 +296,74 @@ def arg_enum_rust_definition(arg):
     return definition_text
 
 def engineering_bit_number(raw_bit_number):
+    """
+    Calculate an appropriate engineering bit width based on a raw bit width.
+    
+    Rounds up the raw bit width to the next power of 2, with a minimum of 8 bits.
+    
+    Parameters:
+    -----------
+    raw_bit_number : int
+        The raw bit width (1-128).
+        
+    Returns:
+    --------
+    int
+        The calculated engineering bit width (a power of 2, minimum 8).
+        
+    Raises:
+    -------
+    ValueError
+        If raw_bit_number is not between 1 and 128.
+    """
     if raw_bit_number < 1 or raw_bit_number > 128:
         raise ValueError("raw_bit_number must be between 1 and 128")
     power = 1
     while 2**power < raw_bit_number:
         power += 1
     bit_number = 2**power
+    if bit_number < 8:
+        bit_number = 8
     return (bit_number)
 
 def get_data_type(parent_classes):
-    """Extract the data type from a list of parent class names.
-    Returns the class name that ends with 'DataType' or None if not found."""
+    """
+    Extract the data type from a list of parent class names.
+    
+    Searches through a list of class names to find one ending with 'DataType'.
+    
+    Parameters:
+    -----------
+    parent_classes : list
+        A list of class names to search through.
+        
+    Returns:
+    --------
+    str or None
+        The name of the class ending with 'DataType', or None if none is found.
+    """
     for class_name in parent_classes:
         if class_name.endswith('DataType'):
             return class_name
     return None
 
 def get_base_type(parent_classes):
+    """
+    Determine the base type from a list of parent class names.
+    
+    Checks if the parent classes include common base types like Argument, Member,
+    Parameter, or DataType.
+    
+    Parameters:
+    -----------
+    parent_classes : list
+        A list of class names to search through.
+        
+    Returns:
+    --------
+    str or None
+        The base type name if found, or None if none of the target base types are found.
+    """
     for base_type in ["Argument", "Member", "Parameter"]:
         if base_type in parent_classes:
             return base_type
@@ -117,6 +372,32 @@ def get_base_type(parent_classes):
     return None
 
 def rust_type_definition(pymdb_data_instance, parent_name="MyStruct"):
+    """
+    Generate Rust type definition code from a pymdb data instance.
+    
+    This is the main function for converting pymdb data types to Rust code.
+    It analyzes the pymdb instance, determines its data type, and generates
+    appropriate Rust code including struct fields and necessary type definitions.
+    
+    Parameters:
+    -----------
+    pymdb_data_instance : object
+        A pymdb data instance (Parameter, Argument, Member, etc.).
+    parent_name : str, optional
+        The name of the parent struct, used for inferring unnamed elements. Default is "MyStruct".
+        
+    Returns:
+    --------
+    list
+        A list with two elements:
+        - [0]: The struct field definition including attributes
+        - [1]: Any supporting type definitions needed (like enums)
+        
+    Raises:
+    -------
+    ValueError
+        If the data type cannot be determined or is not supported.
+    """
     parent_classes = list(map(lambda type: type.__name__, type(pymdb_data_instance).mro()))
     data_type = get_data_type(parent_classes)
     base_type = get_base_type(parent_classes)
@@ -136,6 +417,8 @@ def rust_type_definition(pymdb_data_instance, parent_name="MyStruct"):
     definition_text = ["",""]
     if pymdb_data_instance.short_description is not None:
         definition_text[0] += ("\n\t/// "+str(pymdb_data_instance.short_description)+"\n")
+    
+    # Handle IntegerDataType
     if data_type == 'IntegerDataType':
         if pymdb_data_instance.encoding is None or pymdb_data_instance.encoding.bits is None:
             raw_bit_number = 8
@@ -151,12 +434,15 @@ def rust_type_definition(pymdb_data_instance, parent_name="MyStruct"):
         else:
             definition_text[0] += ("\tpub "+sc_instance_name+": u"+eng_bit_number_str+",\n")
     
+    # Handle BooleanDataType
     elif data_type == 'BooleanDataType':
         definition_text[0] += ("\t#[bits(1)]\n\tpub "+sc_instance_name+": bool,\n")
     
+    # Handle StringDataType
     elif data_type == 'StringDataType':
         definition_text[0] += "\t#[null_terminated]\n\tpub "+sc_instance_name+": String,\n"
     
+    # Handle ArrayDataType
     elif data_type == 'ArrayDataType':
         definition_text = rust_type_definition(pymdb_data_instance.data_type, parent_name=pymdb_data_instance.name)
         definition_text[0] = definition_text[0].replace(': ', ': Vec<').replace(',\n', '>,\n')
@@ -165,6 +451,7 @@ def rust_type_definition(pymdb_data_instance, parent_name="MyStruct"):
         if pymdb_data_instance.long_description is not None:
             definition_text[1] = "/// "+pymdb_data_instance.long_description+"\n" + definition_text[1]
     
+    # Handle EnumeratedDataType
     elif data_type == 'EnumeratedDataType':
         definition_text[0] += "\t#[bits("+str(pymdb_data_instance.encoding.bits)+")]\n"
         definition_text[0] += "\tpub "+pymdb_data_instance.name+": "+pascalcase(pymdb_data_instance.name)+",\n"
@@ -175,6 +462,7 @@ def rust_type_definition(pymdb_data_instance, parent_name="MyStruct"):
         if pymdb_data_instance.long_description is not None:
             definition_text[1] = "/// "+pymdb_data_instance.long_description+"\n" + definition_text[1]
     
+    # Handle AggregateDataType
     elif data_type == 'AggregateDataType':
         struct_name = pascalcase(pymdb_data_instance.name)
         definition_text[0] += "\tpub "+sc_instance_name+": "+struct_name+",\n"
@@ -190,6 +478,28 @@ def rust_type_definition(pymdb_data_instance, parent_name="MyStruct"):
         definition_text[1] += insert
         definition_text[1] += "}\n\n"
         definition_text[1] += append
+    
+    # Handle FloatDataType
+    elif data_type == 'FloatDataType':
+        if pymdb_data_instance.encoding is None or pymdb_data_instance.encoding.bits is None:
+            raw_bit_number = 32
+            print("RCCN-Warning: No encoding for "+base_type+" "+pymdb_data_instance.name+" found. Using 32 as default for raw bit number.")
+        else:
+            raw_bit_number = pymdb_data_instance.encoding.bits
+        raw_bit_number_str = str(raw_bit_number)
+        if raw_bit_number == 32:
+            eng_bit_number = 32
+        elif raw_bit_number == 64:
+            eng_bit_number = 64
+        else:
+            print("RCCN-Warning: Given raw bit number for "+base_type+" \'"+pymdb_data_instance.name+"\' is not equal to 32 or 64. A engineering bit number of 64 will be used.")
+            eng_bit_number = 64
+        eng_bit_number_str = str(eng_bit_number)
+        definition_text[0] += "\t#[bits("+raw_bit_number_str+")]\n"
+        definition_text[0] += ("\tpub "+sc_instance_name+": f"+eng_bit_number_str+",\n")
+    
+    # Handle unsupported data types
     else:
         definition_text = ["\t// Please implement datatype "+data_type+" here.\n", ""]
+    
     return definition_text

{rccn_gen-1.2.0.dist-info → rccn_gen-1.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rccn_gen
-Version: 1.2.0
+Version: 1.3.1
 Summary: A python based generator for RACCOON OS source files in Rust from yamcs-pymdb config files.
 Project-URL: Homepage, https://gitlab.com/rccn/pymdb_code_generation
 Project-URL: Issues, https://gitlab.com/rccn/pymdb_code_generation/issues
@@ -29,10 +29,11 @@ To see whats new, see the [CHANGELOG](CHANGELOG.md).
 ## Using the Generator
 The generator is based on [`pymdb`](https://github.com/yamcs/pymdb) and uses the same structure. Where `pymdb` gives the user freedom in defining systems, subsystems and their respective relations, the definitions for rust code generation is more restricted. For the rust generation, the user is bound to the following classes:
 - `Application`,
-- `Service`, and
-- `RCCNCommand`.
+- `Service`,
+- `RCCNCommand`, and
+- `RCCNContainer`.
 
-All classes inherit from pymdb's Subsystem class and extend their functionality. This means that an existing pymdb definition can be used to generate rust code by renaming the respective instances. No functionality for pymdb's XTCE generation will be lost. 
+The Application and Service classes inherit from pymdb's Subsystem class and extend their functionality. The RCCNCommand extends the Command class and the RCCNContainer extends the Container class of pymdb. This means that an existing pymdb definition can be used to generate rust code by renaming the respective instances. No functionality for pymdb's XTCE generation will be lost. 
 
 A root system may be defined for the satellite.
 ```python
@@ -44,7 +45,7 @@ An application can be defined with the following statement.
 ```python
 app = Application(system=root_system, name="ExampleApp", apid=42)
 ```
-It has the obligatory arguments **system**, **name**, **apid** and **export_directory**. After all Applications, Services and RCCNCommands are defined, the rust code generator can be called on the application with `app.generate_rccn_code(export_directory='.')`.
+It has the obligatory arguments **system**, **name** and **apid**. After all Applications, Services and RCCNCommands are defined, the rust code generator can be called on the application with `app.generate_rccn_code(export_directory='.')`.
 
 ### Service
 
@@ -81,7 +82,7 @@ my_command = RCCNCommand(
 service.add_command(my_command)
 ```
 
-The only obligatory arguments are **name** and a **subtype assignment**, like shown in the example. The connection to a service can also be achieved with base commands, where every base command must be unique to a service. For example:
+The only obligatory argument is **name**. If the subtype assignment is not given, a value will be chosen automatically. The connection to a service can also be achieved with base commands, where every base command must be unique to a service. For example:
 
 ```python
 base_cmd = RCCNCommand(
@@ -98,6 +99,34 @@ my_command = RCCNCommand(
 )
 ```
 
+### RCCNContainer
+A container to hold telemetry information can be created with:
+```python
+my_container = RCCNContainer(
+    system=service,
+    name='BatteryInformation',
+    short_description='This container holds information on battery voltage and current'
+)
+my_container.add_integer_parameter_entry(
+    name='BatteryNumber',
+    minimum=1,
+    maximum=4,
+    encoding=IntegerEncoding(bits=3),
+    short_description='Number of the battery'
+)
+my_container.add_float_parameter_entry(
+    name='Current',
+    units='Ampere',
+    encoding=FloatEncoding(bits=32),
+    short_description='Electric current of the battery.'
+)
+my_container.add_float_parameter_entry(
+    name='Voltage',
+    units='Volts',
+    encoding=FloatEncoding(bits=32),
+    short_description='Electric voltage of the battery.'
+)
+```
 ## Output
 From the python configuration, the `main.rs`, `service.rs`, `command.rs`, `mod.rs`, `Cargo.toml` and `telemetry.rs` files are generated and are structured accordingly:
 - rccn_usr_example_app/

{rccn_gen-1.2.0.dist-info → rccn_gen-1.3.1.dist-info}/RECORD

@@ -1,7 +1,7 @@
 rccn_gen/LICENSE,sha256=ixuiBLtpoK3iv89l7ylKkg9rs2GzF9ukPH7ynZYzK5s,35148
 rccn_gen/__init__.py,sha256=rBnqIw3uQk-uBbRh9VnungoTRSr2V0Bqos32xFZ44Eo,168
-rccn_gen/systems.py,sha256=vGsCyVkwrsFgYqHDL_bPPv8FuX3pIHYUwfIRB5YUWrY,37414
-rccn_gen/utils.py,sha256=VKnTC2hrgMyLdneksAifnqEgXO27zLQJ9x5igaF35rE,8269
+rccn_gen/systems.py,sha256=NewVHJVITt3svMBkAigD23Wl3_-srjNBbiMsOqUstg4,83907
+rccn_gen/utils.py,sha256=q5YSmyc3qADNYcycxQJBvrG6Df8CJelL4lhXF-dN_Ms,17016
 rccn_gen/text_modules/cargo_toml/cargo.txt,sha256=AYjSo3WJE7lhOcJaiNgXP9Y-DXHDIFIt6p42rDTVNVE,427
 rccn_gen/text_modules/command/command.txt,sha256=8Y-uJilhFLoinftIbn7uKfia9LLMZno2LkoDJ-4Y-9M,345
 rccn_gen/text_modules/command/command_module_enum.txt,sha256=35sBlAV_CzQw95Uf2dNynrYOxVD2tT2XWfEvS4Zx_KY,121
@@ -14,6 +14,6 @@ rccn_gen/text_modules/mod/mod.txt,sha256=BF8LablBE4ddutdl5m0prvpvLdBRejueVOujkyr
 rccn_gen/text_modules/service/command_module_match_cmd.txt,sha256=eVGo6ltuerG37rVxpXtL-JYuLyLW4c0i6NXb5g1_U-A,89
 rccn_gen/text_modules/service/service.txt,sha256=qTxoOD5i7wH4yFiDn13rOJW9hIZyACA8W3m6UABe22U,695
 rccn_gen/text_modules/telemetry/telemetry.txt,sha256=Re1d3BfpyXT_CEe7jJzLF3MARik0-J-K98K85iPOE40,193
-rccn_gen-1.2.0.dist-info/METADATA,sha256=h-4mJGYkmnAxOFD5Pn4ART7ml2VjQPrVdENO2eIVj7s,8967
-rccn_gen-1.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-rccn_gen-1.2.0.dist-info/RECORD,,
+rccn_gen-1.3.1.dist-info/METADATA,sha256=xYy5MKpPdYKRgTCLHeabF2vOG_laMSP1NidCw5FiAeM,9911
+rccn_gen-1.3.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+rccn_gen-1.3.1.dist-info/RECORD,,