Skip to content

Latest commit

 

History

History
297 lines (234 loc) · 7.74 KB

README.md

File metadata and controls

297 lines (234 loc) · 7.74 KB

🚀 Telebrief

Telebrief Preview

Python License Version

Telebrief - a modern tool for analyzing Telegram channels and calculating marketing metrics.

Key Features

  • 📈 Metrics Calculation: View-Rate, activity, engagement
  • 🔍 Deep Analysis: Gini coefficient, percentiles, trends
  • 📅 Time Periods: Analysis for any time period
  • 📋 Data Export: JSON, CSV formats
  • 🔧 CLI Interface: Convenient command interface
  • 📚 Library: Use as a Python library

🏗️ Architecture

📦 telebrief/
├── 📂 telebrief/             # Main package
│   ├── 📂 core/              # Core functionality
│   │   ├── parser.py         # Telegram channel parser
│   │   ├── analyzer.py       # Metrics calculation engine
│   │   ├── exporter.py       # Data export (JSON, CSV)
│   │   └── __init__.py       # Core module exports
│   ├── 📂 models/            # Data models & types
│   │   ├── channel.py        # Channel and ChannelInfo classes
│   │   ├── post.py           # Post dataclass
│   │   ├── metrics.py        # Metrics dataclass
│   │   ├── constants.py      # Application constants
│   │   └── __init__.py       # Model exports
│   ├── 📂 utils/             # Utilities & helpers
│   │   ├── config.py         # Configuration management
│   │   ├── logger.py         # Logging system
│   │   ├── date_utils.py     # Date parsing utilities
│   │   └── __init__.py       # Utility exports
│   ├── cli.py                # Command-line interface
│   ├── __main__.py           # Entry point for uv run telebrief
│   └── __init__.py           # Main package exports
├── 📂 tests/                 # Test suite
│   ├── test_analyzer.py      # Analytics tests
│   ├── test_parser.py        # Parser tests
│   └── __init__.py           # Test utilities
├── 📂 examples/              # Usage examples
│   ├── example_usage.py      # Basic usage example
│   ├── analyze_from_file.py  # Batch analysis
│   ├── analyze_active_channels.py # Channel comparison
│   └── simple_channels.txt   # Sample channel list
├── 📂 .github/               # GitHub workflows
├── 📄 pyproject.toml         # Project configuration
├── 📄 justfile               # Development commands
├── 📄 README.md              # Project documentation
└── 📄 LICENSE                # MIT License

🚀 Quick Start

Installation

# Clone and install
git clone https://github.com/TheQmaks/telebrief.git
cd telebrief

# Using uv (recommended)
uv sync

# Development installation with all extras
uv sync --all-extras

CLI Usage

# Analyze one channel for 30 days
uv run telebrief bloomberg

# Analyze multiple channels for 7 days
uv run telebrief bloomberg,insiderpaper,realta_rent_il --days 7

# Load channels from file
uv run telebrief --channels-file channels.txt --days 7

# Limit number of posts (for active channels)
uv run telebrief bloomberg --days 30 --max-posts 100

# Export to CSV
uv run telebrief bloomberg --format csv

# Use proxy
uv run telebrief bloomberg --proxy 127.0.0.1:8081

# Analyze multiple periods
uv run telebrief bloomberg --periods 7,30

Channel File Format

Create a channels.txt file with channel names:

# Simple channel names
bloomberg

# Channels with @ symbol
@insiderpaper

# Telegram URL's
https://t.me/Realta_Rent_IL

# Comments and empty lines are supported
# This is a comment

Library Usage

from telebrief import TelegramParser, MetricsAnalyzer, DataExporter
from telebrief.utils import Config

# Quick analysis
from telebrief import quick_analyze

result = quick_analyze('bloomberg', days=7)
print(f"View-Rate: {result['metrics']['average_vr_percent']:.1f}%")

# Detailed usage
config = Config()
config.add_channel('bloomberg')

# Parse channel
parser = TelegramParser(config)
channel = parser.parse_channel('bloomberg', days=30)

# Analyze metrics
analyzer = MetricsAnalyzer()
metrics = analyzer.analyze_channel(channel)

# Export results
exporter = DataExporter()
json_file = exporter.export_channel_json(channel, metrics=metrics)

print(f"View-Rate: {metrics.average_vr_percent:.1f}%")
print(f"Activity: {metrics.posts_per_day:.1f} posts/day")
print(f"Results saved: {json_file}")

📊 Metrics

Telebrief calculates 20+ analytical metrics:

Basic Metrics

  • total_posts - Number of posts in sample
  • avg_views_per_post - Average number of views
  • median_views_per_post - Median number of views

View-Rate Metrics

  • average_vr_percent - Average View-Rate (%)
  • median_vr_percent - Median View-Rate (%)
  • percentile_90_vr - 90th percentile VR
  • consistency_index_percent - Content stability index

Audience Activity

  • posts_per_day - Publication frequency
  • active_subs_estimate - Active audience estimate
  • activation_ratio_percent - Activation ratio

Content Quality

  • top_10_percent_share - Share of top 10% posts by views
  • gini_coefficient - Gini inequality coefficient
  • engagement_quality - Qualitative engagement assessment

🔧 Configuration

from telebrief.utils import Config

config = Config()

# Network settings
# In my case it was required for MITM and Telegram API debugging during development.
config.network.use_proxy = True
config.network.proxy_host = "127.0.0.1"
config.network.proxy_port = 8081
config.network.verify_ssl = False

# Parsing settings
config.parsing.default_days = 30
config.parsing.max_posts = 100

# Adding channels
config.add_channel('channel1')
config.add_channel('channel2')

📈 Output Example

{
  "info": {
    "channel": "bloomberg",
    "name": "Bloomberg",
    "subscribers": 162268,
    "description": "The first word in business news.",
    "first_post_date": "2019-11-14T21:43:15",
    "channel_age_days": 2039
  },
  "posts": [
    {
      "post_id": "3063",
      "views": 19700,
      "date": "2025-06-13T00:46:47",
      "author": "bloomberg",
      "text": "Some post text..."
    },
    {
      "post_id": "3064",
      "views": 20100,
      "date": "2025-06-13T01:03:36",
      "author": "bloomberg",
      "text": "🚨 LIVE BLOG:..."
    },
    {
      "post_id": "3065",
      "views": 19100,
      "date": "2025-06-13T05:00:05",
      "author": "bloomberg",
      "text": "🚨 Here's the latest:..."
    }
  ],
  "metrics": {
    "total_posts": 4,
    "total_views": 74100,
    "analysis_period_days": 3,
    "avg_views_per_post": 18525,
    "median_views_per_post": 19400,
    "max_views": 20100,
    "min_views": 15200,
    "average_vr_percent": 11.42,
    "median_vr_percent": 11.96,
    "percentile_90_vr": 12.31,
    "percentile_75_vr": 12.2,
    "posts_per_day": 1.33,
    "active_subs_estimate": 19980,
    "activation_ratio_percent": 12.31,
    "top_10_percent_share": 27.13,
    "gini_coefficient": 0.05,
    "engagement_quality": "Average",
    "content_consistency": "High",
    "posting_frequency": "Medium"
  }
}

🛠️ Development

Quick Commands

# Show all available commands
just

# Install development dependencies
just install-dev

# Sync dependencies from lock file
just sync

# Run tests
just test

# Format and check code
just pre-commit

# Analyze a channel for testing
just analyze bloomberg 7

📋 Requirements

  • Python 3.11+
  • requests >= 2.31.0
  • beautifulsoup4 >= 4.12.0
  • lxml >= 4.9.0
  • html2text >= 2020.1.16

📄 License

MIT License - see LICENSE file.

Made with ❤️ by Anatoliy Fedorenko