rcomments 0.1.2__tar.gz

rcomments-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 RComments Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rcomments-0.1.2/MANIFEST.in

@@ -0,0 +1,6 @@
+include LICENSE
+include README.md
+include .env.example
+recursive-include rcomments *.py
+recursive-include tests *.py
+global-exclude *.py[cod] __pycache__ *.so *.dylib .DS_Store

rcomments-0.1.2/PKG-INFO

@@ -0,0 +1,471 @@
+Metadata-Version: 2.4
+Name: rcomments
+Version: 0.1.2
+Summary: A minimal Flask + PostgreSQL commenting system with hierarchical threading, soft deletion, rate limiting, and XSS protection
+Author-email: Rahul Naik <rnnutube@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2024 RComments Contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com
+Project-URL: Repository, https://github.com
+Project-URL: Issues, https://github.com
+Keywords: flask,postgresql,comments,forum,discussion
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Framework :: Flask
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Flask>=2.0.0
+Requires-Dist: Flask-SQLAlchemy>=3.0.0
+Requires-Dist: Flask-Migrate>=4.0.0
+Requires-Dist: psycopg2-binary>=2.9.0
+Requires-Dist: python-dotenv>=0.21.0
+Requires-Dist: email-validator>=2.0.0
+Requires-Dist: bleach>=6.0.0
+Requires-Dist: limits>=3.0.0
+Requires-Dist: flask-limiter>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-flask>=1.2.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# RComments
+
+A minimal, secure, and feature-rich commenting system for Flask + PostgreSQL applications.
+
+## Features
+
+- **Hierarchical Threading**: Support for nested replies with unlimited depth
+- **Flexible Identity**: Registered usernames or anonymous commenting
+- **Metadata Tracking**: Automatic UTC timestamps and IP logging for moderation
+- **XSS Protection**: HTML sanitization to prevent injection attacks
+- **Rate Limiting**: Configurable limits to prevent spam
+- **Soft Deletion**: Comments can be marked as deleted without permanent removal
+- **Automatic Cleanup**: Permanently removes old comments (30 days or 150 comments limit)
+- **Easy Integration**: Simple Flask blueprint registration
+
+## Installation
+
+```bash
+pip install rcomments
+```
+
+
+
+## Quick Start
+
+### 1. Configuration
+
+Create a `.env` file in your project root:
+
+```env
+DATABASE_URL=postgresql://username:password@localhost/yourdb
+SECRET_KEY=your-flask-secret-key
+RATE_LIMIT=10 per minute
+MAX_COMMENT_AGE_DAYS=30
+MAX_TOTAL_COMMENTS=150
+ALLOW_ANONYMOUS=true
+```
+
+### 2. Flask Application Setup
+
+```python
+from flask import Flask
+from flask_sqlalchemy import SQLAlchemy
+from flask_limiter import Limiter
+from rcomments import init_config, init_routes, db as rcomments_db
+
+app = Flask(__name__)
+app.config.from_prefixed_env()  # Loads from .env
+
+# Initialize RComments
+init_config()
+
+# Setup database (use your existing SQLAlchemy instance or create a new one)
+db = SQLAlchemy(app)
+rcomments_db.init_app(app)
+
+# Setup rate limiter
+limiter = Limiter(
+    app,
+    key_func=lambda: request.headers.get("X-Forwarded-For", request.remote_addr)
+)
+
+# Initialize routes
+init_routes(app, limiter)
+
+if __name__ == "__main__":
+    app.run(debug=True)
+```
+
+### 3. Database Migration
+
+Initialize the database:
+
+```bash
+# Using Flask-Migrate (recommended)
+flask db init
+flask db migrate -m "Initial RComments tables"
+flask db upgrade
+
+# Or using the CLI
+rcomments-cli init-db
+```
+
+## API Endpoints
+
+All endpoints are prefixed with `/api/comments`.
+
+### GET `/api/comments`
+
+Fetch all top-level comments with nested replies.
+
+**Query Parameters:**
+- `sort` (optional): `asc` or `desc` (default: `desc`)
+- `limit` (optional): Maximum number of top-level comments
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": 1,
+      "content": "This is a comment",
+      "author_name": "John",
+      "is_anonymous": false,
+      "status": "ACTIVE",
+      "created_at": "2024-01-15T10:30:00Z",
+      "parent_id": null,
+      "replies": []
+    }
+  ],
+  "count": 1
+}
+```
+
+### POST `/api/comments`
+
+Create a new comment.
+
+**Request Body:**
+```json
+{
+  "content": "Your comment text",
+  "author_name": "Your Name",
+  "author_email": "email@example.com",  // optional
+  "parent_id": 1,  // optional, for replies
+  "is_anonymous": false  // optional, default: false
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "id": 2,
+    "content": "Your comment text",
+    "author_name": "Your Name",
+    "is_anonymous": false,
+    "status": "ACTIVE",
+    "created_at": "2024-01-15T10:35:00Z",
+    "parent_id": 1
+  },
+  "message": "Comment created successfully"
+}
+```
+
+### GET `/api/comments/<id>`
+
+Fetch a single comment with its replies.
+
+### DELETE `/api/comments/<id>`
+
+Soft delete a comment (marks as `[Comment removed]`).
+
+### GET `/api/comments/<id>/replies`
+
+Fetch direct replies for a comment.
+
+### GET `/api/comments/stats`
+
+Get comment statistics.
+
+### POST `/api/comments/cleanup`
+
+Trigger cleanup of old comments (admin only - secure this in production!).
+
+**Query Parameters:**
+- `dry_run=true` - Preview what would be deleted
+
+## Security Features
+
+### XSS Protection
+
+All comment content is automatically sanitized using `bleach`. Only basic formatting tags are allowed:
+- `<b>`, `<i>`, `<u>`, `<em>`, `<strong>`, `<br>`, `<p>`
+
+### Rate Limiting
+
+Configurable rate limits prevent automated spamming. Default: 10 comments per minute per IP.
+
+### IP Logging
+
+IP addresses are hashed (SHA-256) for privacy while maintaining moderation capabilities.
+
+### Soft Deletion
+
+Comments can be soft-deleted via the DELETE endpoint, which marks them with status `DELETED` and replaces content with `[Comment removed]`. This preserves thread structure while hiding content.
+
+### Automatic Cleanup
+
+The cleanup process permanently removes comments from the database based on two limits:
+1. **Age**: Comments older than 30 days (configurable) are **permanently deleted**
+2. **Count**: If total active comments exceed 150 (configurable), oldest comments are **permanently deleted**
+
+**Note**: Cleanup removes both top-level comments and replies. The `dry_run` mode allows previewing what would be deleted without making changes.
+
+## Integration with React/TypeScript
+
+Example React component:
+
+```tsx
+import React, { useState, useEffect } from 'react';
+import axios from 'axios';
+
+interface Comment {
+  id: number;
+  content: string;
+  author_name: string;
+  is_anonymous: boolean;
+  created_at: string;
+  parent_id: number | null;
+  replies: Comment[];
+}
+
+const CommentSection: React.FC = () => {
+  const [comments, setComments] = useState<Comment[]>([]);
+  const [newComment, setNewComment] = useState({
+    content: '',
+    author_name: '',
+    author_email: '',
+    is_anonymous: false,
+    parent_id: null as number | null
+  });
+
+  useEffect(() => {
+    fetchComments();
+  }, []);
+
+  const fetchComments = async () => {
+    const response = await axios.get('/api/comments');
+    setComments(response.data.data);
+  };
+
+  const submitComment = async (e: React.FormEvent) => {
+    e.preventDefault();
+    await axios.post('/api/comments', newComment);
+    setNewComment({ content: '', author_name: '', author_email: '', is_anonymous: false, parent_id: null });
+    fetchComments();
+  };
+
+  const deleteComment = async (id: number) => {
+    await axios.delete(`/api/comments/${id}`);
+    fetchComments();
+  };
+
+  return (
+    <div className="comment-section">
+      <h2>Comments</h2>
+
+      <form onSubmit={submitComment}>
+        <textarea
+          value={newComment.content}
+          onChange={(e) => setNewComment({...newComment, content: e.target.value})}
+          placeholder="Your comment..."
+          required
+        />
+        <input
+          type="text"
+          value={newComment.author_name}
+          onChange={(e) => setNewComment({...newComment, author_name: e.target.value})}
+          placeholder="Your name"
+          required
+        />
+        <input
+          type="email"
+          value={newComment.author_email}
+          onChange={(e) => setNewComment({...newComment, author_email: e.target.value})}
+          placeholder="Email (optional)"
+        />
+        <label>
+          <input
+            type="checkbox"
+            checked={newComment.is_anonymous}
+            onChange={(e) => setNewComment({...newComment, is_anonymous: e.target.checked})}
+          />
+          Post anonymously
+        </label>
+        <button type="submit">Post Comment</button>
+      </form>
+
+      <div className="comments-list">
+        {comments.map(comment => (
+          <CommentItem
+            key={comment.id}
+            comment={comment}
+            onReply={(parentId) => setNewComment({
+              ...newComment,
+              parent_id: parentId,
+              content: '',
+            })}
+            onDelete={deleteComment}
+          />
+        ))}
+      </div>
+    </div>
+  );
+};
+
+const CommentItem: React.FC<{ comment: Comment; onReply: (id: number) => void; onDelete: (id: number) => void }> = ({
+  comment,
+  onReply,
+  onDelete
+}) => {
+  const [showReplyForm, setShowReplyForm] = useState(false);
+
+  return (
+    <div className="comment" style={{ marginLeft: comment.parent_id ? '20px' : '0' }}>
+      <div className="comment-header">
+        <strong>{comment.author_name}</strong>
+        {comment.is_anonymous && <span> (Anonymous)</span>}
+        <small>{new Date(comment.created_at).toLocaleString()}</small>
+      </div>
+      <div className="comment-content" dangerouslySetInnerHTML={{ __html: comment.content }} />
+      <div className="comment-actions">
+        <button onClick={() => setShowReplyForm(!showReplyForm)}>Reply</button>
+        <button onClick={() => onDelete(comment.id)}>Delete</button>
+      </div>
+
+      {showReplyForm && (
+        <form onSubmit={(e) => { e.preventDefault(); onReply(comment.id); }}>
+          <textarea placeholder="Your reply..." required />
+          <button type="submit">Post Reply</button>
+        </form>
+      )}
+
+      {comment.replies && comment.replies.length > 0 && (
+        <div className="replies">
+          {comment.replies.map(reply => (
+            <CommentItem
+              key={reply.id}
+              comment={reply}
+              onReply={onReply}
+              onDelete={onDelete}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default CommentSection;
+```
+
+## Command Line Interface
+
+RComments includes a CLI for database management:
+
+```bash
+# Initialize database and migrations
+rcomments-cli init-db
+
+# Create and apply migrations
+rcomments-cli migrate-db
+
+# Clean up old comments
+rcomments-cli cleanup [--dry-run]
+
+# Show statistics
+rcomments-cli stats
+```
+
+## Configuration Options
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DATABASE_URL` | `postgresql://localhost/rcomments` | PostgreSQL connection string |
+| `SECRET_KEY` | `dev-secret-key-change-in-production` | Flask secret key |
+| `RATE_LIMIT` | `10 per minute` | Rate limit format |
+| `MAX_COMMENT_AGE_DAYS` | `30` | Maximum age of comments in days |
+| `MAX_TOTAL_COMMENTS` | `150` | Maximum total active comments |
+| `ALLOW_ANONYMOUS` | `true` | Allow anonymous comments |
+| `REQUIRE_EMAIL_ANONYMOUS` | `false` | Require email for anonymous users |
+
+## Development
+
+### Setup
+
+```bash
+
+cd rcomments
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+pytest tests/ -v
+```
+
+### Code Formatting
+
+```bash
+black rcomments/
+flake8 rcomments/
+mypy rcomments/
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+
+
+