my-ask-lib 0.2.1

A simple custom input validation utility

my-ask-lib (Ultimate Edition) 👑

"เขียนฟังก์ชันรับ Input บรรทัดเดียว ดักจับได้ทุกสถานการณ์"

หมดปัญหาการเขียนลูป while True, try-except, และเงื่อนไข if-else ซ้ำๆ ทุกครั้งที่ต้องการรับค่าจากผู้ใช้ ไลบรารีนี้จะรวมทุกตรรกะการตรวจสอบความถูกต้อง (Validation) ขั้นสูงไว้ในฟังก์ชันเดียว พร้อมการแสดงผลแจ้งเตือนที่สวยงามด้วย rich.logging

---

🔥 ฟีเจอร์เด่น (Superpowers)

• 🛡️ Auto-Validation: ตรวจสอบประเภทข้อมูลให้อัตโนมัติ (str, int, float, ฯลฯ)
• 🧠 Smart Boolean: แปลงค่า Yes/No, ใช่/ไม่, True/False, 1/0 เป็น True/False ของ Python ได้อย่างอัจฉริยะ
• 🎯 Choices Enforcement: ล็อกตัวเลือกให้พิมพ์ได้เฉพาะค่าที่กำหนดเท่านั้น
• 📏 Range Control: ควบคุมช่วงของตัวเลข (ค่าต่ำสุด/สูงสุด) โดยไม่ต้องเขียนโค้ดเพิ่ม
• 🔍 Regex Pattern: ดักจับฟอร์แมตขั้นสูง เช่น Email, เบอร์โทรศัพท์, หรือรหัสเฉพาะตัวด้วย Regular Expression
• 🤫 Secret Input: ซ่อนการพิมพ์บนหน้าจอ Terminal สำหรับการรับรหัสผ่าน
• ⏱️ Max Retries: จำกัดจำนวนครั้งที่กรอกผิด ป้องกันผู้ใช้กรอกมั่วจนระบบค้าง
• 💡 Smart Prompt: แสดงคำใบ้ ช้อยส์ หรือค่า Default บน Prompt ให้อัตโนมัติ

---

🚀 การติดตั้ง

pip install my-ask-lib

---

🎯 ตัวอย่างการใช้งานจริง (Examples)

ดึงฟังก์ชัน ask ไปใช้งานในโปรเจกต์ของคุณ:

from my_ask import ask

# 1. ระบบเลือกเมนู (Enforce Choices)
role = ask("เลือกสิทธิ์การใช้งาน", choices=["admin", "user", "guest"])
# แสดงผล: เลือกสิทธิ์การใช้งาน (choices: admin, user, guest):

# 2. ระบบคุมช่วงตัวเลข (Min / Max Validation)
score = ask("กรอกคะแนนสอบ", type_fn=int, min_val=0, max_val=100)
# ถ้ากรอกต่ำกว่า 0 หรือเกิน 100 ระบบจะเตือนและดีดให้กรอกใหม่ทันที

# 3. ตรวจสอบฟอร์แมตอีเมลด้วย Regex (Pattern Matching)
email_pattern = r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$"
email = ask("กรอก Email", pattern=email_pattern, error_msg="รูปแบบอีเมลไม่ถูกต้องนะ!")

# 4. รับรหัสผ่านแบบซ่อนตัวอักษร (Secret Input)
password = ask("กรอกรหัสผ่าน", secret=True)

# 5. แปลงค่า Boolean อัจฉริยะ (Smart Bool)
is_ready = ask("คุณพร้อมหรือยัง? (y/n)", type_fn=bool)
# รองรับทั้ง: y, yes, true, 1, ใช่, n, no, false, 0, ไม่

# 6. ตั้งค่าเริ่มต้น และจำกัดจำนวนครั้งที่กรอกผิด (Default & Max Retries)
speed = ask("ตั้งค่าความเร็ว", type_fn=int, default=60, max_retries=3)
# ถ้ากด Enter ผ่านเลยจะได้ค่า 60 ทันที แต่ถ้าพิมพ์มั่วเกิน 3 ครั้งจะโยน TimeoutError ออกมา

---

⚙️ รายละเอียดพารามิเตอร์ (API Reference)

Parameter	Type	Default	Description
prompt	str	Required	ข้อความที่ต้องการแสดงเพื่อขอรับข้อมูลจากผู้ใช้
type_fn	Callable	str	ฟังก์ชันแปลงประเภทข้อมูล เช่น int, float, bool (มีระบบ Smart Bool ในตัว)
validate	Callable / List	None	ฟังก์ชันหรือ Lambda สำหรับเช็คเงื่อนไขเพิ่มเติม (ใส่เป็นลิสต์ของหลายฟังก์ชันได้)
choices	List	None	ลิสต์รายการข้อมูลที่อนุญาตให้ผู้ใช้กรอกเท่านั้น
default	Any	None	ค่าเริ่มต้นที่จะคืนกลับไปทันทีหากผู้ใช้กด Enter ผ่าน (ค่าว่าง)
min_val	int / float	None	ค่าตัวเลขต่ำสุดที่ยอมรับได้
max_val	int / float	None	ค่าตัวเลขสูงสุดที่ยอมรับได้
pattern	str (Regex)	None	สตริง Regular Expression ที่ใช้ตรวจสอบรูปแบบของข้อมูล
secret	bool	False	หากเป็น True จะทำการซ่อนตัวอักษรขณะพิมพ์ (เหมาะสำหรับรหัสผ่าน)
max_retries	int	None	จำกัดจำนวนครั้งที่กรอกผิด หากเกินกำหนดจะระเบิด TimeoutError
error_msg	str	None	ข้อความแจ้งเตือนแบบกำหนดเองเมื่อเกิดการกรอกข้อมูลผิดพลาด
allow_empty	bool	False	หากเป็น True จะยอมให้ค่าว่างผ่านไปได้โดยคืนค่ากลับเป็น None (กรณีไม่มี default)

---

📝 License

MIT License