diff --git a/Configuration-Guide%3A-%60item_attributes%60.md b/Configuration-Guide%3A-%60item_attributes%60.md new file mode 100644 index 0000000..50fc7e7 --- /dev/null +++ b/Configuration-Guide%3A-%60item_attributes%60.md @@ -0,0 +1,265 @@ +# 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: +```python +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: +```python +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: +```python +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: +```python +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: +```python +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: + ```python + 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: + ```python + 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: + ```python + 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: + ```python + 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: + ```python + 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. + +--- \ No newline at end of file