1 Configuration Guide: `item_attributes`

Candifloss edited this page 2025-03-08 07:14:15 +00:00

Table of Contents

• Configuration Guide for item_attributes
• Base Attribute Properties
• Attribute Types
• 1. textAttribute
• Properties:
• Validation Rules:
• Example:
• 2. intAttribute
• Properties:
• Validation Rules:
• Example:
• 3. floatAttribute
• Properties:
• Validation Rules:
• Example:
• 4. dateAttribute
• Properties:
• Validation Rules:
• Example:
• 5. selectAttribute
• Properties:
• Validation Rules:
• Example:
• Validation Rules
• Best Practices
• Additional Notes

Configuration Guide for item_attributes

The item_attributes list in config.py defines the structure and behavior of items in your inventory management system. Each item in the list is an instance of a class from definitions/attribute.py. This guide explains how to configure these attributes, their validation rules, and best practices.

---

Base Attribute Properties

All attribute types inherit from the Attribute base class and share the following properties:

Property	Type	Description
attrib_name	str	The name of the attribute (used in the database and code).
display_name	str	The name displayed in the UI (e.g., form labels, table headers).
html_input_type	str	The HTML input type (e.g., text, number, date, select).
required	bool	Whether the attribute is required (default: False).
unique	bool	Whether the attribute value must be unique (default: False).
primary	bool	Whether the attribute is the primary key (default: False).
default_val	Optional[str]	The default value for the attribute (default: None).
compareto	Optional[List[Tuple[str, str]]]	Constraints comparing this attribute to another (e.g., [("lt", "other_attrib")]).

---

Attribute Types

1. textAttribute

Used for string/text data.

Properties:

Property	Type	Description
regex	Optional[str]	A regex pattern to validate the input (e.g., r"^[A-Z0-9]+$").
min_length	Optional[int]	Minimum allowed length of the string (default: None).
max_length	Optional[int]	Maximum allowed length of the string (default: 50).
allowed_chars	Optional[str]	A string of allowed characters (e.g., "abcdefghijklmnopqrstuvwxyz").

Validation Rules:

• The regex pattern must match the input (if provided).
• The input length must be between min_length and max_length (if specified).
• The input must only contain characters from allowed_chars (if provided).
• If default_val is provided, it must satisfy all the above rules.

Example:

textAttribute(
    attrib_name="hostname",
    display_name="Host Name",
    html_input_type="text",
    required=True,
    unique=True,
    regex=r"^[a-z0-9.-_]+$",  # Only lowercase letters, numbers, dots, hyphens, and underscores
    min_length=3,
    max_length=50,
    allowed_chars="abcdefghijklmnopqrstuvwxyz0123456789.-_"
)

---

2. intAttribute

Used for integer data.

Properties:

Property	Type	Description
min_val	Optional[int]	Minimum allowed value (default: None).
max_val	Optional[int]	Maximum allowed value (default: None).
step	int	Step value for the HTML input (default: 1).

Validation Rules:

• The input must be an integer.
• The input must be between min_val and max_val (if specified).
• The step value must be a positive integer and smaller than the range (max_val - min_val).
• If default_val is provided, it must satisfy all the above rules.

Example:

intAttribute(
    attrib_name="staffnum",
    display_name="Staff No.",
    html_input_type="number",
    required=True,
    min_val=100000,  # 6 digits
    max_val=99999999,  # 8 digits
    step=1
)

---

3. floatAttribute

Used for floating-point data.

Properties:

Property	Type	Description
min_val	Optional[float]	Minimum allowed value (default: None).
max_val	Optional[float]	Maximum allowed value (default: None).
step	float	Step value for the HTML input (default: 0.1).

Validation Rules:

• The input must be a floating-point number.
• The input must be between min_val and max_val (if specified).
• The step value must be positive and smaller than the range (max_val - min_val).
• If default_val is provided, it must satisfy all the above rules.

Example:

floatAttribute(
    attrib_name="price",
    display_name="Price",
    html_input_type="number",
    required=True,
    min_val=0.0,
    max_val=1000.0,
    step=0.01
)

---

4. dateAttribute

Used for date data.

Properties:

Property	Type	Description
min_val	Optional[str]	Minimum allowed date (format: YYYY-MM-DD, default: None).
max_val	Optional[str]	Maximum allowed date (format: YYYY-MM-DD, default: None).

Validation Rules:

• The input must be a valid date in YYYY-MM-DD format.
• The input must be between min_val and max_val (if specified).
• If default_val is provided, it must satisfy all the above rules.

Example:

dateAttribute(
    attrib_name="warrantyfrom",
    display_name="Warranty From",
    html_input_type="date",
    required=True,
    min_val="2020-01-01",
    max_val="2030-12-31"
)

---

5. selectAttribute

Used for dropdown selection menus.

Properties:

Property	Type	Description
options	List[str]	A list of allowed options (e.g., ["Active", "Inactive"]).

Validation Rules:

• The input must be one of the options in the options list.
• If default_val is provided, it must be one of the options.

Example:

selectAttribute(
    attrib_name="status",
    display_name="Status",
    html_input_type="select",
    required=True,
    options=["Active", "Inactive"],
    default_val="Active"
)

---

Validation Rules

Each attribute class has a validate() method that ensures the configuration is valid. Common validation rules include:

• Required Fields: Must have a value.
• Unique Fields: Must not conflict with existing values.
• Regex Patterns: Must match the input (for textAttribute).
• Numeric Values: Must fall within the specified range (for intAttribute and floatAttribute).
• Dates: Must be in the correct format and within the allowed range (for dateAttribute).
• Select Options: Must include the default value (for selectAttribute).

---

Best Practices

1. Primary Key:

   • Ensure one attribute is marked as primary=True.
   • This attribute will be used as the unique identifier for each item.
   • Example:

     textAttribute(
         attrib_name="assettag",
         display_name="Asset Tag",
         html_input_type="text",
         primary=True
     )
     

2. Unique Fields:

   • Use unique=True for attributes that must have unique values (e.g., assettag).
   • Example:

     textAttribute(
         attrib_name="hostname",
         display_name="Host Name",
         html_input_type="text",
         unique=True
     )
     

3. Default Values:

   • Provide sensible defaults for required fields to simplify user input.
   • Example:

     dateAttribute(
         attrib_name="warrantyfrom",
         display_name="Warranty From",
         html_input_type="date",
         default_val="2020-01-01"
     )
     

4. Validation:

   • Use regex, allowed_chars, and length constraints to enforce data integrity.
   • Example:

     textAttribute(
         attrib_name="hostname",
         display_name="Host Name",
         html_input_type="text",
         regex=r"^[a-z0-9.-_]+$",
         allowed_chars="abcdefghijklmnopqrstuvwxyz0123456789.-_"
     )
     

5. Constraints with compareto:

   • Use compareto to enforce relationships between attributes (e.g., start date < end date).
   • Example:

     dateAttribute(
         attrib_name="start_date",
         display_name="Start Date",
         html_input_type="date",
         compareto=[("lt", "end_date")]
     ),
     dateAttribute(
         attrib_name="end_date",
         display_name="End Date",
         html_input_type="date"
     )
     

---

Additional Notes

• Configuration Validation:
  • The validate_config function in functions/validate_config.py ensures the configuration is valid.
  • It checks for duplicate attribute names, valid attribute properties, and valid compareto constraints.
• Dynamic Table Creation:
  • The create_asset_model function in definitions/models.py dynamically creates the database table based on the item_attributes configuration.

---