nibraslite 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- nibraslite/README.md +294 -0
- nibraslite/__init__.py +4 -0
- nibraslite/browser.py +2071 -0
- nibraslite/convert_cookies.py +175 -0
- nibraslite-0.1.0.dist-info/METADATA +312 -0
- nibraslite-0.1.0.dist-info/RECORD +10 -0
- nibraslite-0.1.0.dist-info/WHEEL +5 -0
- nibraslite-0.1.0.dist-info/entry_points.txt +2 -0
- nibraslite-0.1.0.dist-info/licenses/LICENSE +21 -0
- nibraslite-0.1.0.dist-info/top_level.txt +1 -0
nibraslite/README.md
ADDED
|
@@ -0,0 +1,294 @@
|
|
|
1
|
+
# NibrasLite — مكتبة مساعدة خفيفة لسيلينيوم بواجهة عربية
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
مكتبة بايثون خفيفة تربط كودك بمتصفح Chrome **مستقر ودائم** — النافذة لا تُغلق عند انتهاء السكربت.
|
|
9
|
+
تستورد واجهة السيلينيوم كاملة من مكان واحد، مع نظام بروفايلات، حقن كوكيز، كشف ذاتي، ودعم بروكسي متعدد الأنواع.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## ✨ الميزات
|
|
14
|
+
|
|
15
|
+
| الميزة | الوصف |
|
|
16
|
+
|--------|-------|
|
|
17
|
+
| 🔄 **جلسة دائمة** | شغّل Chrome مرة واحدة، عدّ السكربتات وتبقى النافذة والتبويبات والكوكيز حيّة |
|
|
18
|
+
| 🐍 **واجهة سيلينيوم كاملة** | `By` · `Keys` · `Select` · `ActionChains` · `WebDriverWait` · `EC` + كل الاستثناءات |
|
|
19
|
+
| 🎭 **Stealth مدمج** | إخفاء آثار الأتمتة بـ JavaScript خاص — بلا أي مكتبة ثالثة |
|
|
20
|
+
| 📁 **نظام بروفايلات** | بروفايل دائم افتراضي · بروفايلات مسمّاة · بروفايلات مؤقتة تُحذف تلقائياً |
|
|
21
|
+
| 🍪 **حقن الكوكيز** | لصق جدول DevTools → `new_coc.txt` → تحويله عبر `convert_cookies.py` |
|
|
22
|
+
| 🌐 **بروكسي متعدد** | `proxy_http` · `proxy_https` · `proxy_socks4` · `proxy_socks5` + دالة `proxy_check` |
|
|
23
|
+
| 🖥️ **CLI جاهز** | أوامر مثل `start` · `attach` · `stop` · `status` · `profiles` مباشرة من التيرمينال |
|
|
24
|
+
| 🧪 **فحص ذاتي 20/20** | اختبارات شاملة لكل ميزة للتأكد من عدم regressions |
|
|
25
|
+
| 🪟 **متعدد المنصات** | يعمل على Windows / macOS / Linux (يكشف Chrome تلقائياً) |
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## 📦 التثبيت
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
pip install selenium>=4.48
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
لا تحتاج تثبيت أي حزمة إضافية — المكتبة تعتمد على Selenium فقط.
|
|
36
|
+
|
|
37
|
+
تأكد من وجود Chrome أو Chromium مُثبَّت على جهازك.
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## 🚀 الاستخدام السريع
|
|
42
|
+
|
|
43
|
+
### 1. تشغيل المتصفح والبدء بالفحص
|
|
44
|
+
|
|
45
|
+
```python
|
|
46
|
+
import browser
|
|
47
|
+
|
|
48
|
+
# بدء جلسة دائمة + stealth في سطر واحد
|
|
49
|
+
driver = browser.ensure("https://example.com")
|
|
50
|
+
|
|
51
|
+
# استخدام كامل واجهة السيلينيوم
|
|
52
|
+
driver.find_element("By.NAME", "q").send_keys("nibras")
|
|
53
|
+
driver.find_element("By.NAME", "q").submit()
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### 2. الـ REPL التفاعلي
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
python browser.py start
|
|
60
|
+
python browser.py attach # فتح REPL متصل بالنافذة الحالية
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### 3. سكريبت مستقل
|
|
64
|
+
|
|
65
|
+
```python
|
|
66
|
+
import browser
|
|
67
|
+
|
|
68
|
+
driver = browser.attach() # الربط بنافذة شغّالة (لا تبدأ واحدة جديدة)
|
|
69
|
+
browser.stealth(driver) # تفعيل إخفاء الأتمتة
|
|
70
|
+
driver.get("https://example.com")
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### 4. مثال كامل مع كوكيز
|
|
74
|
+
|
|
75
|
+
```python
|
|
76
|
+
import browser, json
|
|
77
|
+
from pathlib import Path
|
|
78
|
+
|
|
79
|
+
driver = browser.ensure(apply_stealth=True)
|
|
80
|
+
browser.goto(driver, "https://accounts.google.com")
|
|
81
|
+
|
|
82
|
+
cookies = json.loads(Path("session_cookies.json").read_text(encoding="utf-8"))
|
|
83
|
+
ok, failed = browser.inject(driver, cookies)
|
|
84
|
+
print(f"✅ {ok} كوكيز حقّنت | ❌ {failed} فشلت")
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## 📁 هيكل الملفات
|
|
90
|
+
|
|
91
|
+
```
|
|
92
|
+
sel_nibras/
|
|
93
|
+
├── browser.py # ❤️ قلب المكتبة — دورة الحياة + stealth + كوكيز + عناصر + CLI
|
|
94
|
+
├── selfcheck.py # 20 فحص ذاتي يغطي كل الميزات
|
|
95
|
+
├── test.py # سكربت Crashlytics أحادي الاستخدام
|
|
96
|
+
├── example.py # نموذج استخدام عام لأي موقع
|
|
97
|
+
├── probe.py # فاحص سريع لأي صفحة (DOM + stealth report)
|
|
98
|
+
├── convert_cookies.py # يحوّل لصق DevTools → JSON قابل للحقن
|
|
99
|
+
├── browser_guide.html # دليل عربي بصري للمستخدم
|
|
100
|
+
├── README.md # هذا الملف
|
|
101
|
+
├── _profile/ # البروفايل الدائم الافتراضي (gitignored)
|
|
102
|
+
└── profiles/ # بروفايلات مسمّاة إضافية (gitignored)
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
---
|
|
106
|
+
|
|
107
|
+
## ⌨️ أوامر CLI
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
python browser.py start [--url URL] [--name NAME] [--temp] [--port N] [--ua "USER-AGENT"]
|
|
111
|
+
python browser.py attach [--name NAME] [--port N]
|
|
112
|
+
python browser.py status [--all]
|
|
113
|
+
python browser.py stop [--name NAME] [--port N] [--all] [--keep]
|
|
114
|
+
python browser.py profiles
|
|
115
|
+
python browser.py profile new <name>
|
|
116
|
+
python browser.py profile rm <name> [-y]
|
|
117
|
+
python selfcheck.py # تشغيل الفحص الذاتي
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## 🔧 المتغيرات البيئية
|
|
123
|
+
|
|
124
|
+
| المتغيّر | القيمة الافتراضية | الوصف |
|
|
125
|
+
|----------|-------------------|-------|
|
|
126
|
+
| `NIBRAS_PORT` | `9222` | منفذ Debug للربط |
|
|
127
|
+
| `NIBRAS_PROFILE` | `_profile/` | مسار البروفايل الدائم |
|
|
128
|
+
| `NIBRAS_UA` | — | تجاوز User-Agent |
|
|
129
|
+
| `NIBRAS_HEADLESS` | `0` | `1` = وضع بدون واجهة |
|
|
130
|
+
| `NIBRAS_CHROME` | — | مسار Chrome.exe صريح |
|
|
131
|
+
| `NIBRAS_CHROME_VERSION` | — | إصدار Chrome المُستهدف |
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## 🛡️ Stealth — الإخفاء المدمج
|
|
136
|
+
|
|
137
|
+
لا نستخدم أي مكتبة خارجية. الـ stealth مبني بـ JavaScript يُحقَن في كل تبويبة:
|
|
138
|
+
|
|
139
|
+
```javascript
|
|
140
|
+
// ما يخفيه STEALTH_JS:
|
|
141
|
+
navigator.webdriver = false
|
|
142
|
+
navigator.languages = [...] // حسب locale الحقيقي
|
|
143
|
+
navigator.hardwareConcurrency // مطابق لجهاز المستخدم
|
|
144
|
+
window.chrome.runtime // موجود كمتصفح حقيقي
|
|
145
|
+
WebGL vendor/renderer // مخفي (بدون SwiftShader)
|
|
146
|
+
permissions.query(notifications) // لا يعيد "denied"
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
> ⚠️ **تنويه**: هذا Stealth **خفيف** ومخصص للمواقع البسيطة. لا يغطي أنظمة الكشف المتقدمة
|
|
150
|
+
> مثل Google reCAPTCHA v3 أو Cloudflare Turnstile. للمواقع الحساسة استخدم أدوات متخصصة.
|
|
151
|
+
|
|
152
|
+
---
|
|
153
|
+
|
|
154
|
+
## 📊 نظام البروفايلات
|
|
155
|
+
|
|
156
|
+
| النوع | المسار | يبقى بعد الإيقاف؟ | طريقة الاستخدام |
|
|
157
|
+
|-------|--------|:------------------:|----------------|
|
|
158
|
+
| **افتراضي** | `_profile/` | ✅ نعم | `browser.py start` |
|
|
159
|
+
| **مسمّى** | `profiles/<name>/` | ✅ نعم | `browser.py start --name work` |
|
|
160
|
+
| **مسار صريح** | أي مسار تختاره | ✅ نعم | `browser.py start --profile /path/to/dir` |
|
|
161
|
+
| **مؤقت** | OS temp dir | ❌ لا (إلا `--keep`) | `browser.py start --temp` |
|
|
162
|
+
|
|
163
|
+
لتشغيل حسابين في وقت واحد: `--name a` و `--name b` — المكتبة تختار منافذ حرة تلقائياً.
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## 🔗 تدفّق الكوكيز
|
|
168
|
+
|
|
169
|
+
```
|
|
170
|
+
[متصفح آخر] → DevTools → Console → copy table
|
|
171
|
+
↓
|
|
172
|
+
new_coc.txt
|
|
173
|
+
↓
|
|
174
|
+
python convert_cookies.py
|
|
175
|
+
↓
|
|
176
|
+
session_cookies.json
|
|
177
|
+
↓
|
|
178
|
+
browser.inject(driver, cookies)
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
الدالة `inject` تستخدم CDP `Network.setCookie` وتدعم `__Host-*` و `SameSite`.
|
|
182
|
+
|
|
183
|
+
---
|
|
184
|
+
|
|
185
|
+
## 📈 قائمة الـ APIs العامة
|
|
186
|
+
|
|
187
|
+
### دورة الحياة
|
|
188
|
+
```python
|
|
189
|
+
browser.start(...) → port # تشغيل Chrome مستقل
|
|
190
|
+
browser.attach(...) → driver # ربط بنافذة شغّالة
|
|
191
|
+
browser.ensure(url, ...) → driver # الكل في واحد (start + attach + stealth)
|
|
192
|
+
browser.kill(...) # إيقاف Chrome الخاص بنا فقط
|
|
193
|
+
browser.is_alive(port) → bool
|
|
194
|
+
browser.close_browser(driver) # إغلاق النافذة كلها
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
### البروفايلات
|
|
198
|
+
```python
|
|
199
|
+
browser.list_profiles() → list[(name, size_bytes)]
|
|
200
|
+
browser.delete_profile(name, yes=False)
|
|
201
|
+
browser.running_instances() → list[(port, profile)]
|
|
202
|
+
browser.find_port(name=None) → int | None
|
|
203
|
+
browser.next_free_port() → int
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
### الكوكيز
|
|
207
|
+
```python
|
|
208
|
+
browser.cookies_load(path) → list[dict]
|
|
209
|
+
browser.cookies_save(driver, path)
|
|
210
|
+
browser.inject(driver, cookies) → (ok_count, fail_count)
|
|
211
|
+
browser.clear(driver, domain=None)
|
|
212
|
+
browser.list_cookies(driver)
|
|
213
|
+
browser.from_devtools_table(text) → list[dict]
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
### الـ Stealth
|
|
217
|
+
```python
|
|
218
|
+
browser.stealth(driver, all_tabs=True)
|
|
219
|
+
browser.check_stealth(driver) → dict{raw, tests, passed}
|
|
220
|
+
browser.print_stealth(driver) → bool
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
### العناصر والانتظار
|
|
224
|
+
```python
|
|
225
|
+
browser.wait(driver, sel, state, timeout=20) → WebElement
|
|
226
|
+
browser.wait_all(driver, sel, timeout=20) → list[WebElement]
|
|
227
|
+
browser.wait_gone(driver, sel, timeout=20) → bool
|
|
228
|
+
browser.exist / visible / clickable(driver, sel, timeout=0) → bool
|
|
229
|
+
browser.one(driver, sel, timeout=0) → WebElement | None
|
|
230
|
+
browser.find(driver, sel) → list[WebElement]
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
### الأحداث
|
|
234
|
+
```python
|
|
235
|
+
browser.goto / click / clickn / type_text / body_text / dump
|
|
236
|
+
browser.eval_js / scroll / screenshot / tabs / new_tab / switch_tab / accept_alert
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
### البروكسي
|
|
240
|
+
```python
|
|
241
|
+
browser.proxy_check("1.2.3.4", 8080, user="u", pass="p") → dict
|
|
242
|
+
browser.proxy_http / proxy_https / proxy_socks4 / proxy_socks5
|
|
243
|
+
browser.proxy_combine("socks5", "addr", port)
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
### كائن Browser (الواجهة الشاملة)
|
|
247
|
+
```python
|
|
248
|
+
from browser import Browser, By
|
|
249
|
+
b = Browser.ensure("https://example.com")
|
|
250
|
+
b.find_element(By.ID, "q") # → دالة سيلينيوم أصلية (marshaled تلقائياً)
|
|
251
|
+
b.click("#go") # → دالة مكتبتنا
|
|
252
|
+
b.wait("#t", "visible", 5) # → دالة مكتبتنا
|
|
253
|
+
b.driver # → WebDriver الخام
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
---
|
|
257
|
+
|
|
258
|
+
## 🧪 التشغيل
|
|
259
|
+
|
|
260
|
+
```bash
|
|
261
|
+
# تشغيل الفحص الذاتي الكامل
|
|
262
|
+
python selfcheck.py
|
|
263
|
+
|
|
264
|
+
# تشغيل مثال عام
|
|
265
|
+
python example.py
|
|
266
|
+
|
|
267
|
+
# فحص صفحة محددة
|
|
268
|
+
python probe.py
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
---
|
|
272
|
+
|
|
273
|
+
## ⚠️ ملاحظات مهمة
|
|
274
|
+
|
|
275
|
+
- **لا تستخدم `driver.quit()`** — يغلق النافذة الدائمة؛ استخدم `browser.close_browser()` أو `browser.py stop`
|
|
276
|
+
- **لا ترفع `new_coc.txt` أو `session_cookies.json`** — تحوي بيانات دخول سرّية
|
|
277
|
+
- البروفايل `_profile/` يعيش بين الجلسات = تسجيل الدخول محفوظ
|
|
278
|
+
- `NIBRAS_*` هي البادئة الوحيدة المعتمدة حالياً (تم التصحيح من `SEL_BINRAS_*`)
|
|
279
|
+
|
|
280
|
+
---
|
|
281
|
+
|
|
282
|
+
## 🤝 المساهمة
|
|
283
|
+
|
|
284
|
+
1. اقرأ [README.md](README.md) (هذا الملف) قبل أي تعديل
|
|
285
|
+
2. أضف الدالة الجديدة في `browser.py`
|
|
286
|
+
3. أضف اختباراً في `selfcheck.py`
|
|
287
|
+
4. حدّث هذا الملف
|
|
288
|
+
5. اختبر: `python selfcheck.py`
|
|
289
|
+
|
|
290
|
+
---
|
|
291
|
+
|
|
292
|
+
## 📜 الرخصة
|
|
293
|
+
|
|
294
|
+
MIT — حرية الاستخدام والتعديل والتوزيع.
|
nibraslite/__init__.py
ADDED