🛡️ Pasban | پاسبان
Pure Persian Text Processing Library | کتابخانهٔ پردازش متن پارسی سره
🌐 تارنما • 📚 راهنما • 📦 PyPI • 💬 تلگرام • 🐙 GitHub
این پروژه بخشی از پروژهٔ بزرگ پاسبان پارسی است. برای آشنایی و بهره‌گیری از پاسبان می‌توانید به تارنما و کانال تلگرام پاسبان سر بزنید.
🇬🇧 English
What is Pasban?
Pasban is a high-performance Python library for detecting and replacing foreign (non-Persian) words in Persian text. Built with speed and accuracy in mind, it offers:
- ⚡ Lightning Fast: Aho-Corasick algorithm for multi-pattern matching (17-30× faster)
- 🎯 Highly Accurate: Regex-based engine available for maximum precision
- 🧹 Smart Processing: Advanced normalization and contextual cleaning
- 📊 Comprehensive Reports: Detailed statistics and Persian-language summaries
- 🔌 Fully Offline: Works offline after initial database download
- 🔧 Extensible: Easy-to-manage word database
⚠️ Internet Required: First-time database download and updates require an internet connection. If you're in a restricted region, you may need a VPN for initial setup.
Database Source
Pasban automatically downloads its word database from the
keyaruga33/pasban_db repository on first run. The database contains
thousands of foreign words and their Persian equivalents, maintained and updated regularly.
Quick Start
pip install pasban
from pasban.detector import WordDetector
# Initialize detector (downloads database on first run)
detector = WordDetector()
# Detect foreign words
text = "من با کامپیوتر کار می‌کنم و از اینترنت استفاده می‌کنم."
result = detector.detect(text)
# View results
print(f"Foreign words found: {result.foreign_words}")
# Output: ['کامپیوتر', 'اینترنت']
print(f"Persian equivalents: {result.words}")
# Output: {'کامپیوتر': 'رایانه', 'اینترنت': 'اینترنت'}
print(f"Foreign word percentage: {result.foreign_percentage:.1f}%")
# Output: 28.6%
# Get full Persian report
print(result.to_summary_text)
Which Detector Should I Use?
| Engine | Speed | Accuracy | Best For |
|---|---|---|---|
| WordDetector ✅ | 17-30× faster | ~98% | Production, large texts, real-time |
| WordDetectorRegex | Slower | ~99%+ | Small texts, maximum precision |
from pasban.detector import WordDetector, WordDetectorRegex
# For most use cases (recommended)
detector = WordDetector()
# For maximum accuracy
detector_regex = WordDetectorRegex()
Performance Benchmark
Tested on Intel Core i7-8650U (100 iterations):
| Text Size | WordDetector | WordDetectorRegex | Speed Gain |
|---|---|---|---|
| Large (1216 chars) | 0.65 ms | 12.09 ms | 18.6× |
| Small (86 chars) | 0.05 ms | 0.92 ms | 17× |
| Pure Persian (94 chars) | 0.04 ms | 1.15 ms | 30× |
Advanced Usage
# Disable normalization for raw text
result = detector.detect(text, normalize=False)
# Disable contextual cleaning for faster processing
result = detector.detect(text, contextual=False)
# Get only the word mappings
words = detector.detect_words(text)
# Output: {'کامپیوتر': 'رایانه', 'اینترنت': 'اینترنت'}
# Reload database after updates
detector.reload()
Documentation
📚 Full documentation: Read the Docs
Requirements
- Python 3.9+
- requests
- Internet connection (only for initial database download)
🇮🇷 پارسی
پاسبان چیست؟
پاسبان کتابخانه‌ای برای پردازش متن پارسی سره است که شناسایی و جایگزینی واژگان بیگانه را با دقت و سرعت بالا انجام می‌دهد. این کتابخانه دارای ویژگی‌های زیر است:
- ⚡ سرعت بسیار بالا: الگوریتم آهو-کُراسیک برای جستجوی چندالگویی (۱۷-۳۰ برابر سریع‌تر)
- 🎯 دقت بالا: موتور برپایهٔ عبارت منظم برای دقت بیشینه
- 🧹 پردازش هوشمند: نرمال‌سازی پیشرفته و پالایش زمینه‌ای
- 📊 گزارش‌های جامع: آمار دقیق و خلاصه‌های پارسی
- 🔌 کاملاً آفلاین: پس از بارگیری نخستین، نیازی به اینترنت ندارد
- 🔧 قابل گسترش: پایگاه واژگان قابل مدیریت
⚠️ نیازمند اینترنت: برای بارگیری نخستین پایگاه‌داده و به‌روزرسانی‌ها به پیوند اینترنت نیاز دارید. اگر در ناحیهٔ محدود شده هستید، ممکن است برای راه‌اندازی نخستین به VPN نیاز داشته باشید.
منبع پایگاه‌داده
پاسبان به‌صورت خودکار پایگاه واژگان خود را از ریپازیتوری
keyaruga33/pasban_db در اجرای نخست بارگیری می‌کند. این پایگاه‌داده شامل
هزاران واژهٔ بیگانه و برابرهای پارسی آن‌هاست که به‌صورت منظم نگهداری و به‌روزرسانی می‌شود.
آغاز پرشتاب
pip install pasban
from pasban.detector import WordDetector
# راه‌اندازی شناساگر (بارگیری پایگاه‌داده در نخست)
detector = WordDetector()
# شناسایی واژگان بیگانه
text = "من با کامپیوتر کار می‌کنم و از اینترنت استفاده می‌کنم."
result = detector.detect(text)
# نمایش براورد ها
print(f"واژگان بیگانه یافته‌شده: {result.foreign_words}")
# دستاورد ها: ['کامپیوتر', 'اینترنت']
print(f"برابرهای پارسی: {result.words}")
# دستاورد ها: {'کامپیوتر': 'رایانه', 'اینترنت': 'اینترنت'}
print(f"درصد واژگان بیگانه: {result.foreign_percentage:.1f}%")
# دستاورد: 28.6%
# دریافت گزارش واژگام به پارسی
print(result.to_summary_text)
کدام موتور را برگزینم؟
| موتور | شتاب | دقت | بهترین برای |
|---|---|---|---|
| WordDetector ✅ | ۱۷-۳۰ برابر پرشتاب‌تر | ~۹۸٪ | تولید، متن‌های بزرگ، بلادرنگ |
| WordDetectorRegex | کندتر | ~۹۹٪+ | متن‌های کوچک، دقت بیشینه |
from pasban.detector import WordDetector, WordDetectorRegex
# برای بیشتر کاربردها (پیشنهاد می‌شود)
detector = WordDetector()
# برای هوشمنداری بیشینه
detector_regex = WordDetectorRegex()
سنجش کارایی
آزمایش شده بر روی Intel Core i7-8565U (۱۰۰ بار):
| اندازهٔ متن | WordDetector | WordDetectorRegex | برتری سرعت |
|---|---|---|---|
| بزرگ (۱۲۱۶ نویسه) | ۰.۶۵ میلی‌ثانیه | ۱۲.۰۹ میلی‌ثانیه | ۱۸.۶ برابر |
| کوچک (۸۶ نویسه) | ۰.۰۵ میلی‌ثانیه | ۰.۹۲ میلی‌ثانیه | ۱۷ برابر |
| پارسی سره (۹۴ نویسه) | ۰.۰۴ میلی‌ثانیه | ۱.۱۵ میلی‌ثانیه | ۳۰ برابر |
کاربرد پیشرفته
# بی کنش کردن نرمال‌سازی برای نوشتار خام
result = detector.detect(text, normalize=False)
# بی کنس کردن پالایش زمینه‌ای برای پردازش سریع‌تر
result = detector.detect(text, contextual=False)
# دریافت فقط دسکشنری واژگان
words = detector.detect_words(text)
# دستاورد: {'کامپیوتر': 'رایانه', 'اینترنت': 'اینترنت'}
# بارگذاری دوبارهٔ پایگاه‌داده پس از به‌روزرسانی
detector.reload()
داکیومنت
📚 راهنمای بکارگیری: Read the Docs
پیش‌نیازها
- پایتون 3.9 یا بالاتر
- requests
- پیوند اینترنت (تنها برای بارگیری نخستین پایگاه‌داده)
Made with ❤️ for Persian Language | با ❤️ برای زبان پارسی
Documentation • PyPI • Issues
1 maintainer
Metadata
1 maintainer
Release files for pasban 1.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pasban-1.0.1.tar.gz | 33.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pasban-1.0.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 61.3 kB
Release files / pasban-1.0.1.tar.gz
| Download URL | pasban-1.0.1.tar.gz |
|---|---|
| Size | 33.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
67a6b11d1518918278322872cdf29de236f05e2b7f21a3c8325497dadbdcd497
|
|
BLAKE2b-256 checksum How to use checksums |
bf28dc982a4af173fc568b48706b700617f9ffc68ba44afb2e482e2cdc4172b1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Release files / pasban-1.0.1-py3-none-any.whl
| Download URL | pasban-1.0.1-py3-none-any.whl |
|---|---|
| Size | 27.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9d84a4c8dae4f87bb781ee12ee17651e5f57003c6b2043953e10f35a71dffe89
|
|
BLAKE2b-256 checksum How to use checksums |
5259a4f44918e3a94c2365b4c4847fa6b84f5f5c6f6a881dd82d0c84e2312fcc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
