PerSent 0.10.0__tar.gz → 0.299.0__tar.gz

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.
@@ -0,0 +1,365 @@
1
+ Metadata-Version: 2.4
2
+ Name: PerSent
3
+ Version: 0.299.0
4
+ Summary: Persian Sentiment Analysis Toolkit
5
+ Home-page: https://github.com/RezaGooner/PerSent
6
+ Author: RezaGooner
7
+ Author-email: RezaAsadiProgrammer@Gmail.com
8
+ Keywords: persian sentiment analysis nlp
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: License :: OSI Approved :: MIT License
11
+ Classifier: Operating System :: OS Independent
12
+ Requires-Python: >=3.8
13
+ Description-Content-Type: text/markdown
14
+ Requires-Dist: hazm>=0.7.0
15
+ Requires-Dist: gensim>=4.0.0
16
+ Requires-Dist: scikit-learn>=1.0.0
17
+ Requires-Dist: pandas>=1.3.0
18
+ Requires-Dist: tqdm>=4.62.0
19
+ Requires-Dist: joblib>=1.1.0
20
+ Requires-Dist: requests>=2.26.0
21
+ Dynamic: author
22
+ Dynamic: author-email
23
+ Dynamic: classifier
24
+ Dynamic: description
25
+ Dynamic: description-content-type
26
+ Dynamic: home-page
27
+ Dynamic: keywords
28
+ Dynamic: requires-dist
29
+ Dynamic: requires-python
30
+ Dynamic: summary
31
+
32
+ # PerSent (Persian Sentiment Analyzer)
33
+
34
+ [![Persian](https://img.shields.io/badge/Persian-فارسی-blue.svg)](README.fa.md)
35
+
36
+ ![PerSent Logo](https://github.com/user-attachments/assets/6bb1633b-6ed3-47fa-aae2-f97886dc4e22)
37
+
38
+ ## Introduction
39
+ PerSent is a practical Python library designed for Persian sentiment analysis. The name stands for "Persian Sentiment Analyzer". Currently in its early testing phase, the library provides basic functionality and is available on [PyPI](https://pypi.org/project/PerSent/). Install it using:
40
+
41
+ ```bash
42
+ pip install PerSent
43
+ ```
44
+
45
+ Current capabilities include:
46
+
47
+ - Sentiment analysis of opinions/comments
48
+
49
+ - Emotion analysis of texts (happiness, sadness, anger, surprise, fear, disgust, calmness)
50
+
51
+ - Analysis of product/service reviews (recommended/not recommended/no idea)
52
+
53
+ - Both single-text and batch CSV processing
54
+
55
+ - Output displayed in terminal or saved to CSV with summary statistics
56
+
57
+ Initial repository that evolved into this library:
58
+ [Click here](https://github.com/RezaGooner/Sentiment-Survey-Analyzer)
59
+
60
+ We welcome user testing and feedback to improve the library. If you encounter bugs or have suggestions, please:
61
+
62
+ - [Contribute](#contribution)
63
+
64
+ For installation issues due to dependency conflicts (especially with mingw-w64), consider using online platforms like DeepNote.com.
65
+
66
+ ## Structure
67
+ ### Comment Analysis Functions
68
+
69
+ ```train(train_csv, test_size=0.2, vector_size=100, window=5)```
70
+
71
+ | Parameter | Data Type | Default Value | Description | Optional/Required |
72
+ |--------------|-----------|---------------|-----------------------------------------------------------------------------|-------------------|
73
+ | `train_csv` | str | - | Path to CSV file containing training data with `body` and `recommendation_status` columns | Required |
74
+ | `test_size` | float | 0.2 | Proportion of test data (between 0.0 and 1.0) | Optional |
75
+ | `vector_size`| int | 100 | Output vector dimension for Word2Vec model (embedding size) | Optional |
76
+ | `window` | int | 5 | Context window size for Word2Vec model | Optional |
77
+
78
+ recommendation_status must be one of:
79
+
80
+ - no_idea
81
+
82
+ - recommended
83
+
84
+ - not_recommended
85
+
86
+ Null/NaN values are converted to no_idea, affecting model accuracy.
87
+
88
+ - Returns test accuracy score.
89
+
90
+ ---
91
+
92
+ ```analyzeText(text)```
93
+
94
+ | Parameter | Data Type | Description | Optional/Required |
95
+ |-----------|-----------|--------------------------------------|-------------------|
96
+ | `text` | str | The Persian text to be analyzed | Required |
97
+
98
+ The core function that analyzes a text and returns one of:
99
+ "not_recommended", "recommended", or "no_idea".
100
+
101
+ ---
102
+
103
+ ```saveModel()```
104
+
105
+ ```loadModel()```
106
+
107
+ Model persistence functions. Models are saved in the model directory.
108
+
109
+ ---
110
+
111
+ ```analyzeCSV(input_csv, output_path, summary_path=None, text_column=0)```
112
+
113
+ | Parameter | Data Type | Default Value | Description | Optional/Required |
114
+ |----------------|-----------------|---------------|-----------------------------------------------------------------------------|-------------------|
115
+ | `input_csv` | str | - | Path to input CSV file containing comments to analyze | Required |
116
+ | `output_path` | str | - | Path where analyzed results CSV will be saved | Required |
117
+ | `summary_path` | str or None | None | Optional path to save summary statistics CSV | Optional |
118
+ | `text_column` | int or str | 0 | Column index (int) or name (str) containing the text to analyze | Optional |
119
+
120
+
121
+ Batch processes comments from a CSV file. For single-column files, text_column isn't needed. Otherwise specify column name/index (0-based, negative indices supported). Output contains:
122
+
123
+ 1- Original text
124
+
125
+ 2- Recommendation status
126
+ Optional summary_path generates statistics:
127
+
128
+ - Total count
129
+
130
+ - Recommended count
131
+
132
+ - Not recommended count
133
+
134
+ - No idea count
135
+
136
+ - Model accuracy (not implemented in current version)
137
+
138
+ Returns a DataFrame and saves results.
139
+
140
+ ---
141
+
142
+ ### Emotion Analysis Functions
143
+
144
+ ```loadLex(csv_file, word_col=0, emotion_col=1, weight_col=2)```
145
+
146
+ | Parameter | Data Type | Default Value | Description | Optional/Required |
147
+ |----------------|-----------------|---------------|-----------------------------------------------------------------------------|-------------------|
148
+ | `csv_file` | str | - | Path to CSV lexicon file | Required |
149
+ | `word_col` | int or str | 0 | Column index (int) or name (str) containing words | Optional |
150
+ | `emotion_col` | int or str | 1 | Column index (int) or name (str) containing emotion labels | Optional |
151
+ | `weight_col` | int or str | 2 | Column index (int) or name (str) containing weight values | Optional |
152
+
153
+ Loads a CSV with three columns:
154
+
155
+ 1- Keywords
156
+
157
+ 2- Emotion (happiness, sadness, anger, fear, disgust, calmness)
158
+
159
+ 3- Emotion weight (defaults to 1 if unspecified, affecting accuracy)
160
+
161
+ Column indices are optional.
162
+
163
+ ---
164
+
165
+ ```train(train_csv, text_col='text', emotion_col='sentiment', weight_col='weight')```
166
+
167
+ | Parameter | Data Type | Default Value | Description | Optional/Required |
168
+ |----------------|-----------------|---------------|-----------------------------------------------------------------------------|-------------------|
169
+ | `train_csv` | str | - | Path to training CSV file | Required |
170
+ | `text_col` | str or int | 'text' | Column name/index containing text data | Optional |
171
+ | `emotion_col` | str or int | 'emotion' | Column name/index containing emotion labels | Optional |
172
+ | `weight_col` | str or int | 'weight' | Column name/index containing weight values | Optional |
173
+
174
+ Trains the emotion model using a CSV with specified column names (optional).
175
+
176
+ ---
177
+
178
+ ```saveModel(model_name='weighted_sentiment_model')```
179
+
180
+ | Parameter | Type | Default Value | Description | Optional/Required |
181
+ |--------------|-------|-----------------------------|-----------------------------------------------------------------------------|-------------------|
182
+ | `model_name` | str | 'weighted_sentiment_model' | Base filename for saving model (without extension) | Optional |
183
+
184
+
185
+ ```loadModel(model_name='weighted_sentiment_model')```
186
+
187
+ | Parameter | Type | Default Value | Description | Optional/Required |
188
+ |--------------|-------|-----------------------------|-----------------------------------------------------------------------------|-------------------|
189
+ | `model_name` | str | 'weighted_sentiment_model' | Base filename of model to load (without extension) | Optional |
190
+
191
+
192
+ Model persistence functions (saved in model directory).
193
+
194
+ ---
195
+
196
+ ```analyzeText(text)```
197
+
198
+ | Parameter | Type | Description | Optional/Required |
199
+ |-----------|------|--------------------------------------|-------------------|
200
+ | `text` | str | Persian text to analyze | Required |
201
+
202
+ Analyzes a single text, returning percentage scores for each emotion.
203
+
204
+ ---
205
+
206
+ ```analyzeCSV(input_csv, output_csv, text_col='text', output_col='sentiment_analysis')```
207
+
208
+ | Parameter | Type | Default Value | Description | Optional/Required |
209
+ |---------------------|---------------|------------------------|-----------------------------------------------------------------------------|-------------------|
210
+ | `input_csv` | str | - | Path to input CSV file containing text to analyze | Required |
211
+ | `output_csv` | str | - | Path to save analyzed results | Required |
212
+ | `text_col` | str/int | 'text' | Column name/index containing text to analyze | Optional |
213
+ | `output_col` | str | 'sentiment_analysis' | Column name for output results | Optional |
214
+
215
+ Batch processes texts from CSV. Returns True on success. Requires:
216
+
217
+ - input_csv path
218
+
219
+ - output_csv path
220
+ Optional column names.
221
+
222
+ ---
223
+
224
+ ## Installation
225
+ Install via pip:
226
+
227
+ ```bash
228
+ pip install PerSent
229
+ ```
230
+
231
+ For specific versions:
232
+
233
+ ```bash
234
+ pip install PerSent==<VERSION_NUMBER>
235
+ ```
236
+
237
+ ## Usage
238
+ - Comment Analysis
239
+
240
+ Basic single-text analysis:
241
+
242
+ ```bash
243
+ from PerSent import CommentAnalyzer
244
+
245
+ analyzer = CommentAnalyzer()
246
+
247
+ '''
248
+ Training (if you have data):
249
+ Requires CSV with comments and recommendation status columns
250
+ Status must be: recommended/not_recommended/no_idea
251
+ '''
252
+ analyzer.train("train.csv")
253
+
254
+ # Load pre-trained model
255
+ analyzer.loadModel()
256
+
257
+ # Predict
258
+ text = "کیفیت عالی داشت" # "Excellent quality"
259
+ result = analyzer.analyzeText(text)
260
+ print(f"Sentiment: {result}") # Output: Sentiment: recommended
261
+ ```
262
+
263
+ The included pre-trained model has ~70% accuracy. For better results, you can train with larger datasets. I've prepared a split dataset (due to size):
264
+
265
+ [Download Here](https://github.com/RezaGooner/Sentiment-Survey-Analyzer/tree/main/Dataset/big_train)
266
+
267
+ ---
268
+
269
+ Batch CSV processing:
270
+
271
+ ```bash
272
+ from PerSent import CommentAnalyzer
273
+ analyzer = CommentAnalyzer()
274
+ analyzer.loadModel()
275
+
276
+ # Basic usage (single-column CSV)
277
+ analyzer.analyzeCSV(
278
+ input_csv="comments.csv",
279
+ output_path="results.csv"
280
+ )
281
+
282
+ # Alternative usage patterns:
283
+ # 1. Using column index (0-based)
284
+ analyzer.analyzeCSV("comments.csv", "results.csv", None, 0)
285
+
286
+ # 2. Negative indices (count from end)
287
+ analyzer.analyzeCSV("comments.csv", "results.csv", None, -1)
288
+
289
+ # 3. Column name
290
+ analyzer.analyzeCSV("comments.csv", "results.csv", None, "نظرات") # "Comments" column
291
+
292
+ # 4. With summary (single-column)
293
+ analyzer.analyzeCSV("comments.csv", "results.csv", "summary.csv")
294
+
295
+ # 5. With summary and column specification
296
+ analyzer.analyzeCSV("comments.csv", "results.csv", "summary.csv", 2)
297
+ ```
298
+
299
+ - Emotion Analysis
300
+
301
+ Single text analysis with pre-trained model:
302
+
303
+ ```bash
304
+ from PerSent import SentimentAnalyzer
305
+
306
+ analyzer = SentimentAnalyzer()
307
+ analyzer.loadModel()
308
+
309
+ sample_text = "امتحانم رو خراب کردم. احساس می‌کنم یک شکست خورده‌ی تمام عیارم."
310
+ # "I failed my exam. I feel like a complete failure."
311
+
312
+ result = analyzer.analyzeText(sample_text)
313
+ for emotion, score in sorted(result.items(), key=lambda x: x[1], reverse=True):
314
+ print(f"{emotion}: {score:.2f}%")
315
+ ```
316
+
317
+ output :
318
+
319
+ ```bash
320
+ غم: 36.00% #Sadness
321
+ عصبانیت: 36.00% #anger
322
+ ترس: 28.00% #fear
323
+ شادی: 0.00% #happiness
324
+ تنفر: 0.00% #disgust
325
+ شگفتی: 0.00% #surprise
326
+ آرامش: 0.00% #calmness
327
+ ```
328
+
329
+ To train your own model:
330
+
331
+ ``` bash
332
+ analyzer.train('emotion_dataset.csv')
333
+ ```
334
+
335
+ Required CSV columns:
336
+
337
+ 1- Keywords
338
+
339
+ 2- Emotion (happiness, sadness, anger, disgust, fear, calmness)
340
+
341
+ 3- Emotion weight
342
+
343
+ Model persistence:
344
+
345
+ ```bash
346
+ analyzer.saveModel("custom_model_name")
347
+ analyzer.loadModel("custom_model_name")
348
+ ```
349
+
350
+ Batch CSV processing:
351
+
352
+ ```bash
353
+ analyzer.analyzeCSV("input.csv", "output.csv")
354
+ ```
355
+
356
+ ## Contribution
357
+ As mentioned, this library needs community collaboration. Please share suggestions, bugs, or feedback via:
358
+
359
+ - [Fork Repository & Pull Request](https://github.com/RezaGooner/PerSent/fork)
360
+
361
+ - [Create Issue](https://github.com/RezaGooner/PerSent/issues/new)
362
+
363
+ - Email: ```RezaAsadiProgrammer@gmail.com```
364
+
365
+ - Telegram: ```@RezaGooner```
@@ -6,5 +6,5 @@ import os
6
6
  MODEL_DIR = Path(__file__).parent / "model"
7
7
  os.makedirs(MODEL_DIR, exist_ok=True)
8
8
 
9
- __version__ = "0.10.0"
9
+ __version__ = "0.299.0"
10
10
  __all__ = ['CommentAnalyzer', 'SentimentAnalyzer', 'MODEL_DIR']