sentiment-analysis-textblob/README.md

A Node.js library for sentiment analysis using TextBlob

# Sentiment Analysis TextBlob 🎨

[![npm](https://img.shields.io/npm/v/sentiment-analysis-textblob.svg?style=flat-square&color=4CAF50)](https://www.npmjs.com/package/sentiment-analysis-textblob)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-v14.2+-green.svg)](https://nodejs.org/)
[![Downloads](https://img.shields.io/npm/dm/sentiment-analysis-textblob.svg?color=2196F3)](https://www.npmjs.com/package/sentiment-analysis-textblob)

<div style="border: 2px solid #4CAF50; padding: 15px; background: #f5f5f5; border-radius: 8px;">
  <h3 style="color: #4CAF50;">Overview</h3>
  A powerful Node.js library for sentiment analysis using [TextBlob](https://textblob.readthedocs.io/). Detect 😊 positive, 😐 neutral, or 😞 negative sentiments across **Windows**, **macOS**, and **Linux**. Ideal for reviews and feedback!
</div>

---


## 🌟 About the Author

<div style="background: #e8f5e9; padding: 10px; border-left: 4px solid #4CAF50;">
  <strong>Nguyễn Đức Trọng</strong>  
  📧 [trong0196@gmail.com](mailto:trong0196@gmail.com)  
  Passionate about NLP and JavaScript, creating tools for text analysis.
</div>

---


## 🚀 Features

- **Simple API**: Supports callbacks and Promises.
- **Sentiment Scores**: Polarity (-1 to 1) & Subjectivity (0 to 1).
- **Cross-Platform**: Works on all major OSes.
- **Practical Use**: Perfect for social media or customer insights.

---


## 📦 Installation

```bash
npm install sentiment-analysis-textblob
```

<div style="background: #e3f2fd; padding: 10px; border-left: 4px solid #2196F3;">
  Auto-installs TextBlob with Python detection (`python` or `python3`). Manual setup required if it fails.
</div>

### Requirements

- **Node.js**: v14.2+
- **Python**: v3.6+, in PATH
- **TextBlob**: NLP library

**Verify Python**:
```bash
python3 --version || python --version
```

**Manual Install**:
```bash
pip3 install textblob || pip install textblob
```

---


## 🎯 Quick Start

### Promise Example
```javascript
const { analyzeSentimentPromise } = require('sentiment-analysis-textblob');

(async () => {
  try {
    const result = await analyzeSentimentPromise('This is awesome!');
    console.log('Result:', result); // { polarity: 0.7, subjectivity: 0.85 }
  } catch (err) {
    console.error('Error:', err.message);
  }
})();
```

### Callback Example
```javascript
const { analyzeSentiment } = require('sentiment-analysis-textblob');

analyzeSentiment('Great experience!', (err, result) => {
  if (err) console.error('Error:', err.message);
  else console.log('Result:', result); // { polarity: 0.6, subjectivity: 0.8 }
});
```

---


## 📋 API

| Method                  | Description                              | Returns          |
|-------------------------|------------------------------------------|------------------|
| `analyzeSentiment(text, callback)` | Analyze text via callback | `void`           |
| `analyzeSentimentPromise(text)`    | Analyze text via Promise  | `Promise<Object>`|

- **text**: `string` - Text input.
- **callback**: `function(err, result)` - Returns `{ polarity, subjectivity }` or error.
- **Promise**: Resolves to `{ polarity, subjectivity }`.

---


## 📊 Output Details

| Property       | Range       | Meaning                                      |
|----------------|-------------|----------------------------------------------|
| `polarity`     | -1 to 1     | 😊 **> 0**: Positive (e.g., 'Great!' ~ 0.7) <br> 😐 **0**: Neutral (e.g., 'A product' ~ 0) <br> 😞 **< 0**: Negative (e.g., 'Bad!' ~ -0.6) |
| `subjectivity` | 0 to 1      | 📝 **0–0.3**: Objective (e.g., '100 pages' ~ 0) <br> 🤔 **0.3–0.7**: Mixed (e.g., 'Okay' ~ 0.5) <br> 💭 **0.7–1**: Subjective (e.g., 'Love it!' ~ 0.9) |

**Example**:
```javascript
// Input: 'Fantastic performance!'
// Output: { polarity: 0.8, subjectivity: 0.75 }
// Meaning: Strong positive, highly opinionated
```

---


## ℹ️ Notes

- **Language**: Optimized for English; non-English needs preprocessing.
- **Dependencies**: Requires Python + TextBlob (auto-installed).
- **Performance**: Suitable for small projects; use VADER for advanced cases.

---


## 🛠️ Troubleshooting

- **Python Not Found**:
  - Install from [python.org](https://www.python.org/downloads/) and add to PATH.
  - Check: `python3 --version` or `python --version`.
  - macOS/Linux: `export PATH="/usr/local/bin:$PATH"` in `~/.bashrc`.

- **TextBlob Failed**:
  - Run: `pip3 install textblob` or `pip install textblob`.
  - Test: `python3 scripts/sentiment.py 'Test text'` (Expected: `{"polarity": 0.0, "subjectivity": 0.0}`).

- **Custom Path** (Rare):
  - Edit `src/index.js`:
    ```javascript
    const options = {
      mode: 'text',
      pythonPath: '/usr/bin/python3', // e.g., 'C:\\Python39\\python.exe' on Windows
      pythonOptions: ['-u'],
      scriptPath: path.join(__dirname, '../scripts'),
      args: [text]
    };
    ```

---


## 🤝 Contribute

💡 Ideas or bugs?  
👉 [GitHub](https://github.com/trong0196/sentiment-analysis-textblob)  
📧 [trong0196@gmail.com](mailto:trong0196@gmail.com)

---


## 📜 License

[MIT](https://opensource.org/licenses/MIT)