# उन्नत नियम क्रियाएँ: पायथन स्क्रिप्ट निष्पादित करना

यह दस्तावेज़ वर्णन करता है कि कस्टम पायथन स्क्रिप्ट को निष्पादित करके सरल पाठ प्रतिस्थापन नियमों की कार्यक्षमता को कैसे बढ़ाया जाए। यह शक्तिशाली सुविधा आपको गतिशील प्रतिक्रियाएँ बनाने, फ़ाइलों के साथ इंटरैक्ट करने, बाहरी एपीआई को कॉल करने और सीधे आपके वाक् पहचान वर्कफ़्लो के भीतर जटिल तर्क लागू करने की अनुमति देती है।

## मूल अवधारणा: `on_match_exec`

केवल टेक्स्ट को बदलने के बजाय, अब आप एक या अधिक पायथन स्क्रिप्ट को उसके पैटर्न से मेल खाने पर निष्पादित करने का नियम बता सकते हैं। यह नियम के विकल्प शब्दकोश में `on_match_exec` कुंजी जोड़कर किया जाता है।

स्क्रिप्ट का प्राथमिक काम मैच के बारे में जानकारी प्राप्त करना, एक क्रिया करना और एक अंतिम स्ट्रिंग लौटाना है जिसे नए टेक्स्ट के रूप में उपयोग किया जाएगा।

### नियम संरचना

स्क्रिप्ट क्रिया वाला नियम इस तरह दिखता है:

__CODE_ब्लॉक_0__
**प्रमुख बिंदु:**
- `on_match_exec` मान एक **सूची** होना चाहिए।
- स्क्रिप्ट मानचित्र फ़ाइल के समान निर्देशिका में स्थित होती हैं, यही कारण है कि `CONFIG_DIR / 'script_name.py'` पथ को परिभाषित करने का अनुशंसित तरीका है।

---

## एक निष्पादन योग्य स्क्रिप्ट बनाना

सिस्टम को आपकी स्क्रिप्ट का उपयोग करने के लिए, इसे दो सरल नियमों का पालन करना होगा:
1. यह एक वैध पायथन फ़ाइल होनी चाहिए (जैसे, `my_script.py`)।
2. इसमें `execute(match_data)` नाम का एक फ़ंक्शन होना चाहिए।

### `निष्पादित(मिलान_डेटा)` फ़ंक्शन

यह सभी निष्पादन योग्य स्क्रिप्ट के लिए मानक प्रवेश बिंदु है। नियम का मिलान होने पर सिस्टम स्वचालित रूप से इस फ़ंक्शन को कॉल करेगा।

- **`match_data` (dict):** एक शब्दकोश जिसमें मैच के बारे में सभी संदर्भ शामिल हैं।
- **रिटर्न वैल्यू (str):** फ़ंक्शन को एक स्ट्रिंग वापस करनी होगी। यह स्ट्रिंग नया संसाधित टेक्स्ट बन जाएगी.

### `मैच_डेटा` शब्दकोश

यह शब्दकोश मुख्य एप्लिकेशन और आपकी स्क्रिप्ट के बीच का सेतु है। इसमें निम्नलिखित कुंजियाँ हैं:

* ``original_text'` (str): वर्तमान नियम से किसी भी प्रतिस्थापन को लागू करने से पहले पूर्ण पाठ स्ट्रिंग।
* ``text_after_replacement'` (str): नियम की मूल प्रतिस्थापन स्ट्रिंग को *बाद* में लागू किया गया था, लेकिन *पहले* आपकी स्क्रिप्ट को कॉल किया गया था। (यदि प्रतिस्थापन `कोई नहीं` है, तो यह `original_text` के समान होगा)।
* ``regex_match_obj'` (re.Match): आधिकारिक पायथन रेगेक्स मैच ऑब्जेक्ट। **कैप्चर ग्रुप** तक पहुंचने के लिए यह बेहद शक्तिशाली है। आप `match_obj.group(1)`, `match_obj.group(2)`, आदि का उपयोग कर सकते हैं।
* ``rule_options'` (dict): स्क्रिप्ट को ट्रिगर करने वाले नियम के लिए संपूर्ण विकल्प शब्दकोश।

---

## उदाहरण

### उदाहरण 1: वर्तमान समय प्राप्त करना (गतिशील प्रतिक्रिया)

यह स्क्रिप्ट दिन के समय के आधार पर वैयक्तिकृत अभिवादन लौटाती है।

**1. नियम (आपकी मानचित्र फ़ाइल में):**
__CODE_ब्लॉक_1__

**2. स्क्रिप्ट (`get_current_time.py`):**
__CODE_ब्लॉक_2__
**उपयोग:**
> **इनपुट:** "क्या समय हुआ है"
> **आउटपुट:** "शुभ दोपहर! अभी 14:30 बजे हैं।"

### उदाहरण 2: सरल कैलकुलेटर (कैप्चर समूहों का उपयोग करके)

यह स्क्रिप्ट गणना करने के लिए रेगेक्स से कैप्चर समूहों का उपयोग करती है।

**1. नियम (आपकी मानचित्र फ़ाइल में):**
__CODE_ब्लॉक_3__

**2. स्क्रिप्ट (`कैलकुलेटर.py`):**
__CODE_ब्लॉक_4__
**उपयोग:**
> **इनपुट:** "55 प्लस 10 की गणना करें"
> **आउटपुट:** "परिणाम 65 है।"

### उदाहरण 3: लगातार खरीदारी सूची (फ़ाइल I/O)

यह उदाहरण दिखाता है कि कैसे एक स्क्रिप्ट उपयोगकर्ता के मूल पाठ का निरीक्षण करके कई कमांड (जोड़ना, दिखाना) को संभाल सकती है, और यह फ़ाइल में लिखकर डेटा को कैसे बनाए रख सकती है।

**1. नियम (आपकी मानचित्र फ़ाइल में):**
__कोड_ब्लॉक_5__

**2. स्क्रिप्ट (`shopping_list.py`):**
__कोड_ब्लॉक_6__
**उपयोग:**
> **इनपुट 1:** "खरीदारी सूची में दूध जोड़ें"
> **आउटपुट 1:** "ठीक है, मैंने खरीदारी सूची में 'दूध' जोड़ दिया है।"
>
> **इनपुट 2:** "खरीदारी सूची दिखाएं"
> **आउटपुट 2:** "सूची में आपके पास है: दूध।"

---

## सर्वोत्तम प्रथाएं

- **प्रति स्क्रिप्ट एक कार्य:** स्क्रिप्ट को एक ही कार्य पर केंद्रित रखें (उदाहरण के लिए, `calculator.py` केवल गणना करता है)।
- **त्रुटि प्रबंधन:** संपूर्ण एप्लिकेशन को क्रैश होने से बचाने के लिए हमेशा अपनी स्क्रिप्ट के तर्क को `try...except` ब्लॉक में लपेटें। `छोड़कर` ब्लॉक से एक उपयोगकर्ता-अनुकूल त्रुटि संदेश लौटाएँ।
- **बाहरी पुस्तकालय:** आप बाहरी पुस्तकालयों (जैसे `अनुरोध` या `विकिपीडिया-एपीआई`) का उपयोग कर सकते हैं, लेकिन आपको यह सुनिश्चित करना होगा कि वे आपके पायथन वातावरण में स्थापित हैं (`पिप इंस्टॉल <लाइब्रेरी-नाम>`)।
- **सुरक्षा:** ध्यान रखें कि यह सुविधा किसी भी पायथन कोड को निष्पादित कर सकती है। केवल विश्वसनीय स्रोतों से प्राप्त स्क्रिप्ट का उपयोग करें।