Add Configuration Guide: item_attributes
parent
c77b78859b
commit
31170899d0
265
Configuration-Guide%3A-%60item_attributes%60.md
Normal file
265
Configuration-Guide%3A-%60item_attributes%60.md
Normal file
@ -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.
|
||||||
|
|
||||||
|
---
|
||||||
Loading…
Reference in New Issue
Block a user