feat(employee): implement employee model with Pydantic validation

Author: PANDATD

python_fundamentals/exercises/employee_salary_module/__init__.py

@@ -0,0 +1,266 @@
+
+# Assignment 01 — Employee Pydantic Model
+
+## Objective
+
+Build a self-validating `Employee` model using **Pydantic**.
+
+This assignment combines:
+
+* Object-Oriented Programming
+* Type Hints
+* Pydantic
+* `Field`
+* `EmailStr`
+* `field_validator`
+* Instance Methods
+* Pytest
+
+---
+
+# Learning Goals
+
+After completing this assignment, you should be able to:
+
+* Create a Pydantic model.
+* Validate data using `Field`.
+* Write custom validation using `field_validator`.
+* Normalize user input.
+* Add instance methods to a Pydantic model.
+* Test validation using `pytest`.
+
+---
+
+# Requirements
+
+Create a file:
+
+```text
+employee.py
+```
+
+Create the following model:
+
+```python
+class Employee(BaseModel):
+```
+
+---
+
+# Fields
+
+Implement the following fields:
+
+| Field       | Type     |
+| ----------- | -------- |
+| employee_id | str      |
+| name        | str      |
+| email       | EmailStr |
+| salary      | float    |
+
+---
+
+# Validation Rules
+
+## employee_id
+
+Rules:
+
+* Must start with `"EMP-"`.
+
+Example:
+
+```text
+EMP-1001
+```
+
+Use:
+
+* `field_validator`
+
+---
+
+## name
+
+Rules:
+
+* Remove leading and trailing whitespace.
+* Convert to Title Case.
+* Minimum length: 3 characters.
+* Alphabetic characters only.
+
+Examples:
+
+Valid
+
+```text
+"   tejas dixit   "
+```
+
+↓
+
+```text
+Tejas Dixit
+```
+
+Invalid
+
+```text
+Tejas123
+```
+
+---
+
+## email
+
+Use:
+
+```python
+EmailStr
+```
+
+---
+
+## salary
+
+Rules:
+
+* Greater than zero.
+
+Use:
+
+```python
+Field(gt=0)
+```
+
+---
+
+# Instance Methods
+
+Implement the following methods.
+
+---
+
+## annual_salary()
+
+Returns:
+
+```text
+monthly salary × 12
+```
+
+Example:
+
+```python
+employee.annual_salary()
+```
+
+---
+
+## apply_raise()
+
+Accepts:
+
+```python
+percentage: float
+```
+
+Updates the employee salary.
+
+Example:
+
+Before
+
+```text
+25000
+```
+
+After
+
+```python
+employee.apply_raise(10)
+```
+
+↓
+
+```text
+27500
+```
+
+This is a **state-changing method**.
+
+---
+
+# Demonstration
+
+Create:
+
+* One valid employee.
+* One invalid email example.
+* One invalid name example.
+* One invalid salary example.
+
+Catch:
+
+```python
+ValidationError
+```
+
+Print the validation errors.
+
+---
+
+# Testing
+
+Create:
+
+```text
+test_employee.py
+```
+
+Write at least four tests.
+
+Required:
+
+* Valid employee
+* Invalid email
+* Annual salary
+* Apply raise
+
+---
+
+# Quality Gates
+
+Your solution must pass:
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy .
+uv run pytest -v
+```
+
+---
+
+# Constraints
+
+* Use type hints everywhere.
+* Write docstrings for all public methods.
+* Do not use `input()`.
+* Do not use global variables.
+* Keep validation inside the model.
+
+---
+
+# Expected Learning Outcome
+
+By completing this assignment, you should understand that a **Pydantic model is still a Python class**.
+
+It can contain:
+
+* Fields
+* Validators
+* Instance methods
+* Business logic
+
+Validation protects the model's data, while methods implement the model's behavior.

python_fundamentals/exercises/employee_salary_module/assignment.md

@@ -0,0 +1,95 @@
+import re
+
+from pydantic import BaseModel, EmailStr, Field, ValidationError, field_validator
+
+ALLOWED_DEPARTMENTS: frozenset[str] = frozenset(
+    {"HR", "MARKETING", "ADMIN", "OPERATIONS"}
+)
+
+
+class Employee(BaseModel):
+    employee_id: str = Field(description="Employee ID")
+    name: str = Field(
+        description="Employee name",
+        min_length=3,
+        max_length=20,
+    )
+    email: EmailStr = Field(description="Employee email")
+    department: str = Field(description="Employee department")
+    salary: float = Field(description="Monthly salary", gt=0)
+    age: int = Field(description="Employee age", ge=18, le=60)
+    is_active: bool = Field(
+        default=False,
+        description="Employee active status",
+    )
+
+    @field_validator("name")
+    @classmethod
+    def validate_name(cls, name: str) -> str:
+        """Validate Employee name and return transomed name"""
+        name = " ".join(name.strip().split()).title()
+
+        if not name.replace(" ", "").isalpha():
+            raise ValueError("Name must contain only alphabetic characters.")
+
+        return name
+
+    @field_validator("department")
+    @classmethod
+    def validate_department(cls, department: str) -> str:
+        """Validate Department"""
+        department = department.strip().upper()
+
+        if department not in ALLOWED_DEPARTMENTS:
+            raise ValueError(f"Department must be one of {sorted(ALLOWED_DEPARTMENTS)}")
+
+        return department
+
+    @field_validator("employee_id")
+    @classmethod
+    def validate_employee_id(cls, employee_id: str) -> str:
+        """Validate Employee id"""
+        employee_id = employee_id.strip().upper()
+
+        if not re.fullmatch(r"EMP-\d+", employee_id):
+            raise ValueError("Employee ID must be in the format EMP-1001.")
+
+        return employee_id
+
+    def annual_salary(self) -> float:
+        """Return annual salary."""
+        return self.salary * 12
+
+    def apply_raise(self, percentage: float) -> None:
+        """Apply a percentage raise and return the updated salary."""
+
+        if percentage <= 0:
+            raise ValueError("Percentage must be greater than 0.")
+
+        self.salary += self.salary * (percentage / 100)
+        return None
+
+
+def main() -> None:
+    try:
+        employee = Employee(
+            employee_id="EMP-1001",
+            name="Tejas     Dixit",
+            email="tejasdixit17@zohomail.in",
+            department="hr",
+            salary=25000,
+            age=25,
+            is_active=True,
+        )
+
+        print(employee.model_dump())
+        print(f"Annual Salary: {employee.annual_salary():,.2f}")
+        employee.apply_raise(percentage=10)
+        print(f"Updated Salary:{employee.salary}")
+
+    except ValidationError as exc:
+        print(exc)
+
+
+if __name__ == "__main__":
+    main()