DEV Community: Fedor Pasynkov

How To Control Brightness In Ubuntu 22.04?

Fedor Pasynkov — Mon, 02 Jun 2025 17:05:19 +0000

Managing screen brightness automatically based on the time of day can significantly improve your computing experience and reduce eye strain. In this guide, we'll create a script that automatically adjusts your screen brightness throughout the day, simulating natural light patterns.

What We'll Build

Our script will:

Morning (7:00-9:00 AM): Gradually increase brightness from 2% to 100%
Day (9:00 AM-5:00 PM): Maintain maximum brightness (100%)
Evening (5:00-11:59 PM): Gradually decrease brightness from 100% to 2%
Night (12:00-6:59 AM): Maintain minimum brightness (2%)

Prerequisites

Ubuntu 22.04 (should work on other Ubuntu versions too)
X11 Server
Terminal access with sudo privileges
A laptop or monitor that supports brightness control

Step 1: Install brightnessctl

First, we need to install brightnessctl, a utility that allows us to control screen brightness from the command line.

sudo apt update
sudo apt install brightnessctl

Verify the installation by checking available brightness controls:

brightnessctl --list

You should see output similar to:

Available devices:
Device 'intel_backlight' of class 'backlight':
    Current brightness: 850 (80%)
    Max brightness: 1060

Step 2: Create the Brightness Control Script

Create a new script file:

nano ~/TimeBasedBrightControl.sh

Add the following content:

#!/bin/bash

# Get current hour and minutes (remove leading zeros)
current_hour=$(date +%-H)
current_minute=$(date +%-M)

# Add debug output
echo "Current time: $current_hour:$current_minute"

# Function to calculate brightness
calculate_brightness() {
    # If time is between 17:00 and 23:59
    if [ $current_hour -ge 17 ] && [ $current_hour -lt 24 ]; then
        # Total minutes from 17:00 to 24:00
        local total_minutes_decrease=420  # 7 hours * 60 minutes

        # Current minutes since 17:00
        local minutes_since_17=$(( (current_hour - 17) * 60 + current_minute ))

        # Linear interpolation from 100% to 2%
        # Formula: 100 - (minutes_since_17 / total_minutes_decrease) * (100 - 2)
        local brightness=$(( 100 - (minutes_since_17 * 98 / total_minutes_decrease) ))

        # Output debug information to stderr
        echo "Time $current_hour:$current_minute. Decreasing brightness." >&2
        echo "Minutes after 17:00: $minutes_since_17" >&2
        echo "Calculated brightness: $brightness%" >&2

        # Limit minimum brightness to 2%
        if [ $brightness -lt 2 ]; then
            brightness=2
        fi

        # Return only numeric value
        echo $brightness
    # If time is between 00:00 and 06:59
    elif [ $current_hour -lt 7 ]; then
        echo "Time $current_hour:$current_minute. Minimum brightness." >&2
        echo 2
    # If time is between 07:00 and 08:59
    elif [ $current_hour -ge 7 ] && [ $current_hour -lt 9 ]; then
        # Total minutes from 07:00 to 09:00
        local total_minutes_increase=120 # 2 hours * 60 minutes

        # Current minutes since 07:00
        local minutes_since_7=$(( (current_hour - 7) * 60 + current_minute ))

        # Linear interpolation from 2% to 100%
        # Formula: 2 + (minutes_since_7 / total_minutes_increase) * (100 - 2)
        local brightness=$(( 2 + (minutes_since_7 * 98 / total_minutes_increase) ))

        # Output debug information to stderr
        echo "Time $current_hour:$current_minute. Increasing brightness." >&2
        echo "Minutes after 07:00: $minutes_since_7" >&2
        echo "Calculated brightness: $brightness%" >&2

        # Limit maximum brightness to 100% (just in case)
        if [ $brightness -gt 100 ]; then
            brightness=100
        fi

        # Return only numeric value
        echo $brightness
    # Otherwise (time between 09:00 and 16:59)
    else
        echo "Time $current_hour:$current_minute. Maximum brightness." >&2
        echo 100
    fi
}

# Get calculated brightness (only number)
brightness=$(calculate_brightness)

# Add debug output
echo "Final brightness: $brightness"

# If brightness is defined, set it
if [ ! -z "$brightness" ]; then
    echo "Setting brightness: $brightness%"
    sudo brightnessctl set "$brightness%"
else
    echo "Brightness not defined (error in calculations)"
fi

Step 3: Make the Script Executable

chmod +x ~/TimeBasedBrightControl.sh

Step 4: Test the Script

Run the script manually to ensure it works:

~/TimeBasedBrightControl.sh

You should see output like:

Current time: 14:30
Time 14:30. Maximum brightness.
Final brightness: 100
Setting brightness: 100%

Step 5: Handle Sudo Requirements

Since we'll be running the script through sudo crontab -e (root crontab), the script will automatically have the necessary privileges to control brightness.

Step 6: Set Up Automation with Cron

⚠️ IMPORTANT: You must use sudo crontab -e instead of regular crontab -e for the brightness control to work properly. Regular user cron jobs don't have the necessary permissions to control system brightness.

Open the root crontab:

sudo crontab -e

Add the following line to run the script every 5 minutes:

*/5 * * * * /bin/bash "/home/username/TimeBasedBrightControl.sh"

Replace username with your actual username. This will:

Run the script every 5 minutes using /bin/bash explicitly
Execute with root privileges (necessary for brightness control)
Log output to ~/brightness.log
Capture both standard output and errors

Example with actual path:

*/5 * * * * /bin/bash "/home/fedor/TimeBasedBrightControl.sh"

Step 7: Monitor the Script

Check if the cron job is working:

tail -f ~/brightness.log

You should see entries being added every 5 minutes.

Understanding the Brightness Calculation

The script uses linear interpolation to smoothly transition brightness:

Evening Transition (17:00-23:59)

Duration: 7 hours (420 minutes)
Range: 100% → 2%
Formula: 100 - (minutes_since_17 * 98 / 420)

Morning Transition (07:00-08:59)

Duration: 2 hours (120 minutes)
Range: 2% → 100%
Formula: 2 + (minutes_since_7 * 98 / 120)

Customization Options

Adjust Time Ranges

To change the time periods, modify these conditions in the script:

# Change evening start time (currently 17:00)
if [ $current_hour -ge 17 ] && [ $current_hour -lt 24 ]; then

# Change morning start time (currently 07:00)
elif [ $current_hour -ge 7 ] && [ $current_hour -lt 9 ]; then

# Change night end time (currently 06:59)
elif [ $current_hour -lt 7 ]; then

Adjust Brightness Levels

To change minimum/maximum brightness levels:

# Change minimum brightness (currently 2%)
echo 2

# In the interpolation formulas, change the range:
# Currently: 98 (which is 100-2)
# For 5%-95% range, use: 90 (which is 95-5)
local brightness=$(( 5 + (minutes_since_7 * 90 / total_minutes_increase) ))

Change Update Frequency

Modify the cron schedule:

# Every minute
* * * * * /home/username/TimeBasedBrightControl.sh

# Every 10 minutes
*/10 * * * * /home/username/TimeBasedBrightControl.sh

# Every 30 minutes
*/30 * * * * /home/username/TimeBasedBrightControl.sh

Troubleshooting

Script Not Running

Check if cron is running: sudo systemctl status cron
Verify root crontab syntax: sudo crontab -l
Check permissions: ls -la ~/TimeBasedBrightControl.sh

Brightness Not Changing

Verify brightnessctl works: sudo brightnessctl set 50%
Check if script runs manually: sudo /bin/bash "/home/username/TimeBasedBrightControl.sh"
Review log file: cat ~/brightness.log

Permission Issues

If you get permission errors:

# Make sure the script has proper permissions
chmod +x ~/TimeBasedBrightControl.sh

# Check if running with sudo crontab
sudo crontab -l | grep TimeBasedBrightControl

Conclusion

This time-based brightness control system provides a smooth, automated way to manage screen brightness throughout the day. The linear interpolation ensures gradual transitions that are easy on the eyes, while the cron-based automation means you'll never have to manually adjust brightness again.

The script is highly customizable, allowing you to adjust time ranges, brightness levels, and update frequencies to match your specific needs and schedule.

Ready Script

You can find the complete working script in this repository: TimeBasedBrightControl

Found this guide helpful? Feel free to customize the script for your needs and share your improvements in the comments below!

How to Make Your Linux Laptop Auto-Shutdown and Show Notifications Based on Battery Level?

Fedor Pasynkov — Mon, 02 Jun 2025 14:30:26 +0000

⚠️ Tested on Ubuntu 22.04 with X Server - May require adjustments for other distributions

Have you ever left your laptop plugged in for hours, slowly damaging the battery? Or worse, forgotten to charge it until it completely dies? This comprehensive guide will help you create a smart battery monitoring system that automatically manages your laptop's charging cycle and prevents battery damage.

💾 Ready to use? Download the complete script from GitHub and skip to Step 4!

🎯 What This Script Does

Our battery monitoring script provides four levels of protection:

🔴 Critical Low (≤39%): Automatically shuts down the laptop to prevent deep discharge
🟡 Low Warning (40-49%): Shows urgent notification to plug in charger
🟠 High Warning (80-89%): Notifies to unplug charger during charging
🔴 Critical High (≥90%): Automatically shuts down to prevent overcharging

📋 Prerequisites

System Requirements

Operating System: Ubuntu 22.04 (tested) - other Linux distributions may require modifications
Display Server: X Server (X11)

Required Packages

# Update package list
sudo apt update

# Install required dependencies
sudo apt install mpg123 yad

# mpg123: for audio notifications
# yad: for GUI notifications (Yet Another Dialog)

🚀 Step 1: Project Setup

Create the project directory and navigate to it:

mkdir ~/AutoBattOff
cd ~/AutoBattOff

🔧 Step 2: Create Configuration File

Create battery_config.env with the following content:

# Battery thresholds (adjust according to your needs)
LOW_BATTERY_THRESHOLD=39
CRITICAL_LOW_BATTERY_THRESHOLD=49
HIGH_BATTERY_THRESHOLD=80
CRITICAL_BATTERY_THRESHOLD=90

# File paths (relative to script directory)
AUDIO_FILE="notification.mp3"
LOG_FILE="battery_log.txt"

# Notification settings
NOTIFICATION_TIMEOUT=10
NOTIFICATION_WIDTH=300
NOTIFICATION_HEIGHT=100

# System environment variables for GUI
DISPLAY=":0"
XAUTHORITY="/home/YOUR_USERNAME/.Xauthority"
XDG_RUNTIME_DIR="/run/user/1000"
DBUS_SESSION_BUS_ADDRESS="unix:path=/run/user/1000/bus"

# Security (CHANGE THIS!)
SUDO_PASSWORD="YOUR_SUDO_PASSWORD"

# Battery path (usually BAT0, but might be BAT1 on some systems)
BATTERY_PATH="/sys/class/power_supply/BAT0"

# Logging
LOG_LEVEL="INFO"

🔐 Important Security Notes:

Replace YOUR_USERNAME with your actual username
Replace YOUR_SUDO_PASSWORD with your actual sudo password
Set restrictive permissions: chmod 600 battery_config.env

🔍 Finding Your Battery Path:

# List available power supplies
ls /sys/class/power_supply/

# Check if BAT0 exists, if not, use BAT1 or whatever you find
ls -la /sys/class/power_supply/BAT*/capacity

🎵 Getting a Notification Sound:

You need an MP3 file named notification.mp3 in your project directory. You can:

# Download a free notification sound
wget https://www.soundjay.com/misc/sounds/bell-ringing-05.mp3 -O notification.mp3

# Or create a simple beep sound with ffmpeg
sudo apt install ffmpeg
ffmpeg -f lavfi -i "sine=frequency=1000:duration=1" notification.mp3

📝 Step 3: Create the Main Script

Create autobattoff.sh:

#!/bin/bash

# Get the directory where the script is located
script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

# Load configuration
config_file="$script_dir/battery_config.env"
if [[ -f "$config_file" ]]; then
    source "$config_file"
    echo "Configuration loaded from $config_file"
else
    echo "Configuration file $config_file not found!"
    exit 1
fi

# Set full file paths
audio_file="$script_dir/$AUDIO_FILE"
log_file="$script_dir/$LOG_FILE"
low_battery_threshold=$LOW_BATTERY_THRESHOLD
critical_low_battery_threshold=$CRITICAL_LOW_BATTERY_THRESHOLD
high_battery_threshold=$HIGH_BATTERY_THRESHOLD
critical_battery_threshold=$CRITICAL_BATTERY_THRESHOLD
sudo_password="$SUDO_PASSWORD"

# Set environment variables from configuration
export DISPLAY="$DISPLAY"
export XAUTHORITY="$XAUTHORITY"
export XDG_RUNTIME_DIR="$XDG_RUNTIME_DIR"
export DBUS_SESSION_BUS_ADDRESS="$DBUS_SESSION_BUS_ADDRESS"

log() {
    echo "$(date) - $1" >> $log_file
}

log "Script started"

# Check for required utilities
if ! command -v mpg123 &> /dev/null; then
    log "mpg123 not found. Please install mpg123."
    exit 1
fi

if ! command -v yad &> /dev/null; then
    log "yad not found. Please install yad."
    exit 1
fi

notify_user() {
    local message="$1"
    local title="$2"
    log "$message"
    mpg123 $audio_file &
    yad --title="$title" --text="$message" --button=OK --width=$NOTIFICATION_WIDTH --height=$NOTIFICATION_HEIGHT --timeout=$NOTIFICATION_TIMEOUT &
    log "Notification sent: $message"
}

check_battery_status() {
    battery_level=$(cat ${BATTERY_PATH}/capacity)
    charging_status=$(cat ${BATTERY_PATH}/status)
    if [[ -z "$battery_level" || -z "$charging_status" ]]; then
        log "Error reading battery data."
        exit 1
    fi
    log "Battery level: $battery_level"
    log "Charging status: $charging_status"
}

check_battery_status

# Main battery check logic
if [[ $battery_level -lt $low_battery_threshold && "$charging_status" != "Charging" ]]; then
    log "Critical battery level. Shutting down..."
    echo $sudo_password | sudo -S /sbin/poweroff
elif [[ $battery_level -ge $low_battery_threshold && $battery_level -le $critical_low_battery_threshold && "$charging_status" != "Charging" ]]; then
    notify_user "URGENT: PLUG IN THE CHARGER!" "Charging Warning"
elif [[ $battery_level -gt $high_battery_threshold && $battery_level -lt $critical_battery_threshold && "$charging_status" == "Charging" ]]; then
    notify_user "Urgently disconnect the charger!" "Charging Warning"
elif [[ $battery_level -ge $critical_battery_threshold && "$charging_status" == "Charging" ]]; then
    log "Battery at 90% or higher. Shutting down laptop..."
    echo $sudo_password | sudo -S /sbin/poweroff
else
    if [[ "$charging_status" == "Charging" ]]; then
        log "Laptop is charging."
    else
        log "Battery charge is normal."
    fi
fi

log "Script completed"

🔧 Step 4: Make Script Executable

chmod +x autobattoff.sh

🧪 Step 5: Test the Script

Manual Testing:

# Test the script manually
./autobattoff.sh

# Check the log file
cat battery_log.txt

# Check current battery status manually
cat /sys/class/power_supply/BAT0/capacity
cat /sys/class/power_supply/BAT0/status

Test Different Scenarios:

Test low battery: Temporarily change LOW_BATTERY_THRESHOLD to a value higher than your current battery level
Test high battery: Plug in charger and temporarily change HIGH_BATTERY_THRESHOLD to a value lower than current level
Test notifications: Ensure you can see and hear notifications

⏰ Step 6: Automate with Cron

Edit your crontab:

# Edit user crontab
crontab -e

# Add this line to check battery every minute
* * * * * /bin/bash "/path/to/your/script/autobattoff.sh"

Verify Cron Job:

# List current user's cron jobs
crontab -l

# Monitor real-time log updates
tail -f battery_log.txt

📊 What the Script Logs

The script creates a battery_log.txt file with entries like:

Script start/completion
Current battery level and charging status
Notifications sent
Shutdown events

You can monitor the log with:

# View recent logs
tail -20 battery_log.txt

# Follow logs in real-time
tail -f battery_log.txt

🛡️ Security Note

The script stores your sudo password in plain text in the configuration file. For better security:

Set restrictive permissions: chmod 600 battery_config.env
Alternatively, you can modify /etc/sudoers to allow passwordless shutdown:

   sudo visudo
   # Add: YOUR_USERNAME ALL=(ALL) NOPASSWD: /sbin/poweroff

🎯 Configuration Tips

Conservative thresholds: Start with 40% for low and 80% for high
Adjust notification timeout: Increase NOTIFICATION_TIMEOUT if you need more time to see notifications
Battery path: Make sure BATTERY_PATH points to your actual battery (check /sys/class/power_supply/)

🚀 Conclusion

You now have a working battery monitoring system that:

✅ Prevents overcharging by shutting down at 90%
✅ Prevents deep discharge by shutting down at 39%
✅ Shows visual and audio notifications
✅ Logs all activities for monitoring

The script runs every minute via cron and automatically protects your battery health.

🔗 Complete Repository: AutoBattOff on GitHub - Ready to download and use!

Setting Up Tailwind CSS v4 in SvelteKit: The Vite Plugin Way (A Guide Based on Real Issues)

Fedor Pasynkov — Fri, 09 May 2025 04:03:32 +0000

Published: 2025-05-11

This guide shows you how to easily set up and integrate the latest Tailwind CSS v4 with your SvelteKit project. We'll walk you through the process step-by-step, focusing on the official and recommended @tailwindcss/vite plugin, which simplifies the setup and avoids complex PostCSS configurations.

Tailwind CSS v4 is currently in Alpha/RC (Release Candidate) stage (as of 2025-05-11 - please update this date). While this means you get to work with cutting-edge features, it also means some aspects might change before the stable release. This guide reflects the current state and best practices. Always refer to the official Tailwind CSS documentation and the Tailwind CSS v4 release notes/discussions for the most up-to-date information.

We'll cover everything from initial project setup with SvelteKit's CLI to configuring Tailwind v4 and using it within your Svelte components.

Important Compatibility Note: Tailwind CSS v4 is designed for modern browsers: Safari 16.4+, Chrome 111+, Firefox 128+. If you need to support older browsers, please stick with v3.4 as v4 relies on modern CSS features like @property and color-mix().

Prerequisites

Before you begin, ensure you have the following:

Node.js and npm/yarn/pnpm: Installed on your system. You can download Node.js from nodejs.org.
A SvelteKit Project: You can create a new one using npm create svelte@latest my-app or npx sv create . as shown below. If you have an existing SvelteKit project, you can adapt the steps.
Package Manager: Know which package manager you're using (npm, yarn, or pnpm).

1. Creating Your SvelteKit Project with Tailwind CSS Integration (via `npx sv create .`)

This section details how to add Tailwind CSS v4 to SvelteKit during project initialization. The npx sv create . CLI provides a streamlined way to scaffold a SvelteKit project and include Tailwind CSS during the initial setup.

Create your project directory: Open your terminal, create the directory for your frontend application, and navigate into it:
```
mkdir frontend
cd frontend
```
Initialize the SvelteKit project using sv: Run the following command in the directory to start your SvelteKit Tailwind v4 integration:
```
npx sv create .
```
Follow the interactive prompts:
- Select your SvelteKit template.
- Answer questions about TypeScript, ESLint, Prettier, and your adapter.
- Crucially, when asked "What would you like to add to your project?", use your arrow keys and spacebar to select the tailwind option.
- Choose your package manager (e.g., npm, yarn, or pnpm).
- The CLI will install dependencies, including Tailwind CSS, and likely create some initial configuration files.

2. Verifying Installed Packages for a Smooth Tailwind v4 Setup in SvelteKit

After npx sv create . completes, let's ensure you have the correct packages installed for integrating Tailwind via the Vite plugin. This is key for a successful Tailwind v4 setup in SvelteKit.

Open package.json: Navigate to the root of your frontend directory (./frontend/) and open the package.json file.
Check devDependencies: Confirm that the following packages are present (in v4-compatible versions, often @latest or @next for pre-releases):
- tailwindcss (v4.x) - The core Tailwind CSS library.
- @tailwindcss/vite - The official Vite plugin for Tailwind CSS. (Crucial for this guide!) You can find more about it on npmjs.com.
- postcss (May be installed as a dependency of Vite or SvelteKit; might be needed for other PostCSS plugins, but not for Tailwind integration via the Vite plugin itself)
- autoprefixer (Not required for vendor prefixes in v4 when using the Vite plugin, but might be present if added by the CLI or for other purposes)
- @sveltejs/kit and @sveltejs/vite-plugin-svelte (installed by the CLI, essential for SvelteKit projects. See SvelteKit docs).

Install or Uninstall as Needed:

# If @tailwindcss/vite is missing:
npm install -D @tailwindcss/vite

# If @tailwindcss/postcss was installed instead of @tailwindcss/vite:
# npm uninstall -D @tailwindcss/postcss # Uninstall if you don't need the PostCSS plugin
npm install -D @tailwindcss/vite

# autoprefixer and postcss-import are NOT needed for Tailwind v4 integration via the Vite plugin.
# You can uninstall them if they aren't required for other purposes:
# npm uninstall -D autoprefixer postcss-import

3. Step-by-Step: Configuring SvelteKit's Vite Setup for Tailwind CSS v4

Since you're integrating Tailwind via the @tailwindcss/vite plugin and skipping the PostCSS config file approach, you'll configure Tailwind directly in your Vite configuration. This is a central part of the Tailwind v4 configuration in SvelteKit.

Open vite.config.ts (or .js): This file is located in the root of your frontend directory.

Configure Vite Plugins: Ensure the tailwindcss() plugin, imported from @tailwindcss/vite, is added to the root plugins array of your Vite configuration:

import { defineConfig } from 'vite';
import { sveltekit } from '@sveltejs/kit/vite';
import tailwindcss from '@tailwindcss/vite'; // Import the Vite plugin

export default defineConfig({
  plugins: [
    sveltekit(),
    tailwindcss(), // Add the Tailwind CSS Vite plugin here!
  ],
  css: {
    // Make sure there is no 'postcss' section configured for Tailwind integration here.
    // If a 'postcss' section exists (e.g., added by the CLI or for other plugins like Autoprefixer),
    // ensure it does NOT include the Tailwind CSS plugin.
    // postcss: { plugins: [] },

    // A community recommendation (might help with Vite plugin issues):
    // transformer: 'lightningcss'
  },
});

Optional: Configure CSS Transformer: Some users report that setting css.transformer: 'lightningcss' in vite.config.ts can help resolve certain issues when using the @tailwindcss/vite plugin. Add this line to the css section if you encounter unexpected behavior:
```
  css: {
    transformer: 'lightningcss'
  },
```

4. Importing Tailwind CSS v4 in Your Main SvelteKit CSS File

Locate the main CSS file that is imported somewhere in your SvelteKit application (e.g., src/app.css). This step is essential to add Tailwind CSS v4 to SvelteKit's styling pipeline.

Use ONLY @import "tailwindcss";: According to the official Tailwind CSS v4 documentation, the correct and only recommended way to include Tailwind's base styles, components, and utilities is with a single @import directive. The @tailwind base;, @tailwind components;, and @tailwind utilities; directives have been removed in v4.
```
@import "tailwindcss";
```
Remove any other old @import or @tailwind directives from this file.

5. Mastering Tailwind CSS v4 Theme Configuration in SvelteKit

In Tailwind CSS v4, the primary and recommended approach for theme configuration shifts to using CSS directly. Understanding this is key for your SvelteKit Tailwind v4 integration.

Configuration via @theme in CSS (Recommended v4 Approach)
- Use @theme in your main CSS file: Define your custom theme properties directly in your main CSS file (e.g., src/app.css) using the @theme directive. These properties will become CSS variables and Tailwind theme tokens. With this approach, the tailwind.config.js file is not needed for theme customization, only potentially for content paths.
```
@import "tailwindcss";

@theme {
  /* Define your custom theme properties as CSS variables */
  --color-brand-primary: #3490dc;
  --font-family-heading: "Georgia", serif;
  --spacing-128: 32rem;
  /* ... other theme variables */
}

/* Rest of your styles */
```
- Automatic Content Detection and @source: Tailwind v4 automatically scans most project files. If you need to include files from non-standard locations (e.g., component libraries in node_modules), use the @source directive in the same CSS file:
```
@import "tailwindcss";
@source "../node_modules/@my-company/ui-lib";
@theme { /* ... */ }
```
- Using tailwind.config.js for Content (Optional): The tailwind.config.js file can still be used solely for defining the content section if you prefer explicitly listing paths or if auto-detection is insufficient:
```
/** @type {import('tailwindcss').Config} */
export default {
  content: [
    './src/**/*.{html,js,svelte,ts}',
    // Explicitly list paths here
  ],
  theme: {
    extend: {
      // This section can be empty or removed if using @theme in CSS
    },
  },
  plugins: [], // corePlugins, safelist, separator options are NOT supported in v4 JS config
};
```
  If you use tailwind.config.js for content, you generally don't need the @config directive in your CSS when using the Vite plugin and @theme for theme definition.

6. Effectively Using Tailwind CSS v4 in Svelte Components (`<style>` blocks)

In Tailwind CSS v4, styles defined within Svelte component <style> blocks (or CSS Modules) do not automatically have access to theme variables, custom utilities, and variants defined in your main CSS file (app.css). Here's how to handle it when you integrate Tailwind 4 with SvelteKit components:

Use @reference (for access to @apply, @utility, and @theme definitions): To gain access to definitions made using @apply, @utility, or @theme in your main CSS file, use the @reference directive within the component's <style> block, pointing to your main CSS file:

<style>
  @reference "../app.css"; /* Path to your main CSS file */

  h1 {
    @apply text-2xl font-bold text-blue-600; /* @apply should now work */
  }
  /* You can also use CSS variables here */
  /* color: var(--color-blue-600); */
</style>

<h1>Hello world!</h1>

Use CSS Variables Directly (Preferred): Often, instead of @apply, you can directly use the corresponding Tailwind CSS variables in your <style> blocks. This is the preferred approach as it's more performant and doesn't require @reference for theme variables defined via @theme in the main CSS:

<style>
  /* No @reference needed if only using theme variables */
  h1 {
    color: var(--color-blue-600); /* Access a color variable */
    font-size: var(--text-2xl); /* Access a text size variable */
    /* ... other styles using variables */
  }
</style>

<h1>Hello world!</h1>

7. Key General v4 Changes and Recommendations for SvelteKit Developers

Be aware of these general changes in Tailwind v4 that might affect your SvelteKit Tailwind v4 integration:

Removed/Renamed Utilities: Many deprecated utilities are removed, some are renamed (e.g., outline-none to outline-hidden), scales are changed (shadow, blur, rounded), and default values are updated (ring from 3px to 1px, border/ring colors to currentColor). Always refer to the official Tailwind CSS v4 upgrade guide for a complete list.
space-x/space-y Selector Change: The selector used by these utilities has changed, which might require adjustments in some complex layouts. Consider using flex or grid with gap as an alternative.
Custom Utilities (@utility): Use the @utility directive instead of @layer utilities and @layer components.
```
@utility my-custom-utility {
  /* Your styles */
}
```
Variables in Arbitrary Values: The syntax for using CSS variables in arbitrary values changed from square brackets to parentheses: bg-[--var] -> bg-(--var).
Prefixes: If you use a prefix, the syntax is now prefix:class (e.g., tw:flex). Configure it within the @import rule: @import "tailwindcss" prefix(tw);.
Using theme(): Using CSS variables directly (var(--color-...)) is recommended. If you use theme(), the syntax is now theme(--variable-name) (e.g., theme(--breakpoint-xl)).
Theme in JavaScript: The resolveConfig function is removed. Use getComputedStyle to access theme CSS variables in JS.

Always consult the official Tailwind CSS documentation for the most current troubleshooting advice.

Conclusion and Next Steps

By following this guide, focusing on the @tailwindcss/vite plugin integration, you should be able to successfully set up and integrate Tailwind CSS v4 with your SvelteKit project. This approach aligns with the latest v4 practices, helping you avoid potential issues related to older PostCSS configurations.

Remember that Tailwind CSS v4 is an evolving tool. Keep an eye on the official Tailwind CSS blog and documentation for updates and new features.

I'd love to hear from you!

Did you find this guide helpful for your SvelteKit Tailwind v4 setup?
Are there any other aspects of Tailwind v4 or SvelteKit integration you'd like to see covered?
Encountered any specific issues or found other solutions?

Please leave a comment below to share your experience, ask questions, or suggest improvements! Your feedback helps make this guide better for everyone.

Happy coding!

Twitch OAuth2 Explained for twitchio Bots: Getting Authorized

Fedor Pasynkov — Wed, 07 May 2025 01:54:31 +0000

Hey developers! If you're looking to build a Twitch bot that can interact with chat, perform moderation actions, or access user data, especially using the powerful twitchio library, you'll need to navigate the world of Twitch OAuth2. It might seem daunting at first, but this guide will walk you through every step, making the process clear and manageable, so you can get your twitchio bot up and running.

What is OAuth 2.0 and Why Do You Need It?

OAuth 2.0 is the industry-standard protocol for authorization. It allows applications (like your twitchio bot) to access user resources on a service (Twitch, in this case) without needing the user's login credentials directly. Instead, it uses access tokens. All the steps described here are essential for your twitchio bot to authenticate and interact with Twitch services.

Here's a quick rundown of the key components you'll be working with:

Access Token: A short-lived credential used to authenticate API requests to Twitch on behalf of a user (your bot). Your twitchio bot will use this token for most of its API calls.
Refresh Token: A long-lived credential used to obtain a new Access Token when the current one expires, without requiring the user to go through the authorization process again. twitchio can be configured to handle token refreshing automatically if you provide it with this token.
Client ID: A public identifier for your application, which you get when you register your app on Twitch. This is fundamental for any Twitch API interaction, including those made by twitchio.
Client Secret: A confidential key known only to your application and Twitch. Treat this like a password! It's used in server-to-server communication, like exchanging an authorization code for tokens, or refreshing tokens, all of which are vital for your twitchio bot's long-term operation.

By the end of this guide, you'll have all these tokens and understand how to use them to power up your Twitch bot, specifically one built with twitchio.

Prerequisites
Step 1: Registering Your Application on the Twitch Developer Portal
Step 2: Defining Necessary Permissions (Scopes)
Step 3: Preparing for Authorization
Step 4: Constructing the Authorization URL
Step 5: Authorizing the Application and Obtaining the Code
Step 6: Exchanging the Authorization Code for Tokens
Step 7: Storing Your Tokens Securely
Step 8: Validating Your Access Token (Recommended)
Step 9: Refreshing the Access Token
Wrapping Up and Next Steps

Prerequisites

Before you dive in, make sure you have:

A Twitch Account for Your Bot: Create a separate Twitch account that your bot will use. Do not use your main Twitch account for the bot.
A Twitch Account for Your Channel: The channel your bot will interact with or moderate.

Step 1: Registering Your Application on the Twitch Developer Portal

To interact with the Twitch API, your bot needs to be registered as an application.

Go to the Twitch Developer Console.
Log in using your main Twitch account (or your developer account). Do not use the bot's account at this stage.
Click the "+ Register Your Application" button.
Fill out the form:
- Name: Choose any name for your application (e.g., "MyAwesomeBot"). IMPORTANT: Do not use the word "Twitch" in the name.
- OAuth Redirect URLs: Enter http://localhost:3000. This URL is used during the authorization process. Even if you don't have a server running at this address, it's required to obtain the authorization code.
- Category: Select "Chat Bot".
Click "Create".

Getting Your Client ID and Client Secret

Once your application is created, you'll see your Client ID. Copy it and save it somewhere safe.

To get your Client Secret:

On your application's page, click the "New Secret" button.
Twitch will generate and display the Client Secret. IMPORTANT: The Client Secret is shown only once. Copy it immediately and store it securely with your Client ID. If you lose it, you'll have to generate a new one.

These credentials are vital for your bot to authenticate with the Twitch API.

Step 2: Defining Necessary Permissions (Scopes)

Scopes define what actions your bot can perform on behalf of the user (the bot's account). For a typical moderation bot, you might need:

chat:read - Read chat messages.
chat:edit - Send chat messages (and delete messages via /delete command).
channel:moderate - Use moderation commands (e.g., /timeout, /ban).
moderator:manage:chat_messages - Allows deleting messages directly via API (if you plan to use this method).
moderator:manage:banned_users - Manage banned users.
moderator:read:followers - Read the list of followers (if your bot needs this).
whispers:read - Read whispers.
whispers:edit - Send whispers.
user:manage:whispers - Manage whispers.

Find the full list of scopes and their descriptions in the official Twitch documentation.

For example, your scopes string might look like this:
chat:read+chat:edit+channel:moderate+moderator:manage:chat_messages
(The + sign is used as a separator when forming the URL, or a space if used in another context).

Step 3: Preparing for Authorization

Log out of your main Twitch account in all your browser tabs. This is crucial to avoid accidentally authorizing the app with your main account.
Log into the Twitch account your bot will use (the bot's account).
(Recommended) Make the bot's account a moderator on your main channel. This expands its capabilities (e.g., higher message rate limits, ability to execute moderation commands). In your main channel's chat, type: /mod YOUR_BOT_ACCOUNT_NAME Replace YOUR_BOT_ACCOUNT_NAME with your bot's actual username.

Step 4: Constructing the Authorization URL

Now, you need to create a special URL. You'll open this URL in the browser where your bot's account is logged in to authorize your application.

The URL structure is:
https://id.twitch.tv/oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost:3000&scope=YOUR_SCOPES&force_verify=true

Replace:

YOUR_CLIENT_ID: With your Client ID from Step 1.
YOUR_SCOPES: With the scopes string defined in Step 2 (e.g., chat:read+chat:edit+channel:moderate). Ensure scopes are separated by +.

Example of a complete URL:
https://id.twitch.tv/oauth2/authorize?response_type=code&client_id=abcdef1234567890&redirect_uri=http://localhost:3000&scope=chat:read+chat:edit+channel:moderate&force_verify=true

The force_verify=true parameter prompts for explicit authorization, even if the user has previously granted permission.

Step 5: Authorizing the Application and Obtaining the Code

Copy the URL you constructed in Step 4.
Paste it into the address bar of the browser where you are logged in as the bot. Hit Enter.
Twitch will ask you to authorize your application to access data according to the specified scopes. Carefully review the requested permissions and click "Authorize".
After successful authorization, the browser will redirect you to the redirect_uri (http://localhost:3000). Since you likely don't have a web server listening there, you'll see an error like "This site can't be reached." This is normal and expected!
The important part: Look at the browser's address bar. The URL will look something like this: http://localhost:3000/?code=LONG_AUTHORIZATION_CODE&scope=requested_scopes
Copy the value of the code parameter from this URL. This is your Authorization Code. It's single-use and has a short lifespan.

Example: If the URL is http://localhost:3000/?code=zyxw9876543210&scope=chat:read+chat:edit, your authorization code is zyxw9876543210.

Step 6: Exchanging the Authorization Code for Tokens (Access & Refresh)

The Authorization Code you just got needs to be exchanged for an Access Token and a Refresh Token. This exchange happens by sending a POST request to the Twitch server. This request must include your Client Secret, so it cannot be done from client-side JavaScript in a browser.

Using `curl` to Exchange the Code for Tokens

curl is a powerful command-line tool for making HTTP requests, available on most operating systems.

Open your terminal or command prompt and execute the following command, substituting your actual values:

curl -X POST "https://id.twitch.tv/oauth2/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET" \
-d "code=YOUR_AUTHORIZATION_CODE" \
-d "grant_type=authorization_code" \
-d "redirect_uri=http://localhost:3000"

Replace:

YOUR_CLIENT_ID: Your Client ID.
YOUR_CLIENT_SECRET: Your Client Secret.
YOUR_AUTHORIZATION_CODE: The Authorization Code obtained in Step 5.

Example JSON response from Twitch:

{
  "access_token": "NEW_ACCESS_TOKEN",
  "refresh_token": "NEW_REFRESH_TOKEN",
  "expires_in": 14058,
  "scope": [
    "chat:read",
    "chat:edit",
    "channel:moderate"
  ],
  "token_type": "bearer"
}

From this response, you need:

access_token: Your Access Token.
refresh_token: Your Refresh Token.

Copy these and store them securely. expires_in indicates the Access Token's lifetime in seconds.

Pro Tip: If you prefer a GUI, tools like Postman or Insomnia can also be used to make this POST request.

Step 7: Storing Your Tokens Securely

You now have all the essential credentials for your bot:

CLIENT_ID
CLIENT_SECRET
ACCESS_TOKEN
REFRESH_TOKEN
BOT_USERNAME (the bot account's username)
CHANNEL_NAME (the channel name where the bot will operate)

It's crucial to store these securely, especially CLIENT_SECRET, ACCESS_TOKEN, and REFRESH_TOKEN. These are the keys your twitchio bot will use to authenticate and function.

Recommended storage methods:

Environment Variables: The most secure method for production. Your twitchio application will read these variables at startup.
.env file: Create a file named .env in your project's root directory and add key-value pairs. Always add .env to your .gitignore file to prevent accidentally committing it to your repository. Your twitchio bot can load these using a library like python-dotenv.

Example .env file content (often used for twitchio bots):

BOT_USERNAME=your_bot_name
CHANNEL_NAME=your_channel_name
CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret
ACCESS_TOKEN=your_access_token
REFRESH_TOKEN=your_refresh_token

Step 8: Validating Your Access Token (Recommended)

To ensure your Access Token is valid and belongs to the correct user (your bot), you can make a validation request.

Request (GET):
URL: https://id.twitch.tv/oauth2/validate
Headers: Authorization: Bearer YOUR_ACCESS_TOKEN

Using curl:

curl -X GET "https://id.twitch.tv/oauth2/validate" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Replace YOUR_ACCESS_TOKEN with the Access Token you obtained.

Example of a successful JSON response:

{
  "client_id": "your_client_id",
  "login": "your_bot_name",
  "scopes": ["chat:read", "chat:edit"],
  "user_id": "bot_user_id",
  "expires_in": 13900 // Remaining token lifetime in seconds
}

Verify that login matches your bot's username and client_id matches your application's Client ID.

Step 9: Refreshing the Access Token

Access Tokens have a limited lifespan (usually a few hours). When it expires, your bot will lose API access. To prevent this, use the Refresh Token to get a new Access Token.

Request (POST):
URL: https://id.twitch.tv/oauth2/token
Body (x-www-form-urlencoded):

grant_type: refresh_token
refresh_token: YOUR_REFRESH_TOKEN
client_id: YOUR_CLIENT_ID
client_secret: YOUR_CLIENT_SECRET

Using curl:

curl -X POST "https://id.twitch.tv/oauth2/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token" \
-d "refresh_token=YOUR_REFRESH_TOKEN" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET"

Replace YOUR_REFRESH_TOKEN, YOUR_CLIENT_ID, and YOUR_CLIENT_SECRET with your values.

Server Response:
The server will return a new access_token and possibly a new refresh_token. Always save the new refresh_token if one is provided, as the old one might become invalid.

{
  "access_token": "LATEST_ACCESS_TOKEN",
  "refresh_token": "POSSIBLY_NEW_REFRESH_TOKEN",
  "scope": ["chat:read", "chat:edit"],
  "token_type": "bearer",
  "expires_in": 14400
}

Update your stored ACCESS_TOKEN and REFRESH_TOKEN with these new values. Your bot should automate this process before the Access Token expires.

Wrapping Up and Next Steps

Congratulations! You've successfully navigated the Twitch OAuth2 process and obtained the necessary tokens. Your bot is now ready for action.

Key Takeaways:

Security First: Always keep your Client Secret, Access Token, and Refresh Token secure. Never expose them in client-side code or commit them to public repositories.
Token Lifecycle: Understand that Access Tokens expire and need to be refreshed using the Refresh Token. Implement logic in your bot to handle this automatically.
Scopes Matter: Only request the permissions (scopes) your bot absolutely needs.

Stay tuned for the next article in this series, where we'll dive into the actual implementation of a Twitch bot using the tokens and knowledge you've gained here!

Now that you have the keys to the kingdom, what cool features are you planning to build for your Twitch bot? Share your ideas or any questions you have in the comments below! Happy coding!

🎬 Movie Magic with Python: Your First Steps into IMDb Data using imdbpy

Fedor Pasynkov — Tue, 06 May 2025 23:12:17 +0000

Ever wondered how to programmatically access the treasure trove of information on IMDb? Whether you're building a movie recommendation engine, a film data analysis tool, or just curious about your favorite series, the imdbpy library for Python is your gateway!

In this guide, we'll walk through how to install imdbpy, search for movies and TV shows, fetch detailed information, and navigate the rich data structures returned. We'll use the iconic series "Breaking Bad" as our running example.

Who is this for?

This article is for Python developers of all levels who want to integrate IMDb data into their applications or scripts. If you love movies and code, you're in the right place!

🛠️ Setting Up: Installation and Initialization

First things first, let's get imdbpy installed. Open your terminal and type:

pip install imdbpy

Once installed, you can import it into your Python script and create an instance of the IMDb class. This object will be your primary tool for interacting with IMDb.

from imdb import IMDb

# Create an instance of the IMDb class
ia = IMDb()
print("IMDb instance created!")

By the way, you can find a complete working code example, which you can run and test, at the following link: working example. This will help you quickly understand how to use the library.

🔎 Searching for Titles

Let's say we want to find "Breaking Bad". The search_movie() method is what we need. It returns a list of Movie objects, which are lightweight summaries.

try:
    search_term = "Breaking Bad"
    # You can limit the number of results with the 'results' parameter
    results = ia.search_movie(search_term, results=1) # Let's get the top result

    if results:
        print(f"Found {len(results)} result(s) for '{search_term}':")
        for movie in results:
            # Each 'movie' object here has basic info like title, year, and IMDb ID
            print(f"- Title: {movie['title']}")
            print(f"  Year: {movie.get('year', 'N/A')}")
            print(f"  IMDb ID: {movie.getID()}")
            # We'll need this ID for the next step!
    else:
        print(f"No results found for '{search_term}'.")

except Exception as e:
    print(f"An error occurred during search: {e}")

You'll notice we get the title, year, and most importantly, the imdbID. For "Breaking Bad", this is typically '0903747'.

🎬 Getting the Full Scoop: Fetching Detailed Information

The initial search gives us basic info. To get all the juicy details – cast, plot, ratings, genres, cover images, and more – we use the get_movie() method with the movieID.

# Assuming 'results' contains our search result and 'movie' is the first item
if results:
    first_result = results[0]
    movie_id = first_result.getID() # e.g., '0903747' for Breaking Bad
    print(f"\nFetching full details for '{first_result['title']}' (ID: {movie_id})...")

    try:
        # This is the magic call! It fetches a wealth of data.
        full_movie = ia.get_movie(movie_id)

        if full_movie:
            print(f"\nSuccessfully fetched details for: {full_movie.get('title')}")
            # Now, 'full_movie' is a rich Movie object.
            # Let's explore what we can get!
        else:
            print(f"Could not fetch details for ID {movie_id}.")

    except Exception as e:
        print(f"An error occurred fetching details for ID {movie_id}: {e}")
else:
    print("No search results to fetch details from.")

📊 Accessing the Data: What's Inside?

The full_movie object now holds a comprehensive dataset. You can access its information like a Python dictionary or using the .get() method (which is safer as it allows default values if a key is missing).

Let's pull out some specific details for "Breaking Bad":

from pprint import pprint # For nicely printing complex data structures

if 'full_movie' in locals() and full_movie: # Check if full_movie exists and is not None
    print("\n" + "="*10 + f" Detailed Info for {full_movie.get('title')} " + "="*10)

    print(f"Localized Title: {full_movie.get('localized title', 'N/A')}")
    print(f"Kind: {full_movie.get('kind', 'N/A')}") # e.g., 'tv series', 'movie'
    print(f"Year: {full_movie.get('year', 'N/A')}")

    if full_movie.get('kind') == 'tv series':
        print(f"Series Years: {full_movie.get('series years', 'N/A')}") # e.g., '2008-2013'
        print(f"Number of Seasons: {full_movie.get('number of seasons', 'N/A')}")

    print(f"Cover URL: {full_movie.get('cover url', 'N/A')}")
    # You could even try to display this image in a rich environment!
    # Example: https://m.media-amazon.com/images/M/MV5BMzU5ZGYzNmQtMTdhYy00OGRiLTg0NmQtYjVjNzliZTg1ZGE4XkEyXkFqcGc@._V1_SX101_CR0,0,101,150_.jpg

    print(f"Rating: {full_movie.get('rating', 'N/A')} (based on {full_movie.get('votes', 'N/A')} votes)")

    print("\nGenres:")
    genres = full_movie.get('genres', [])
    if genres:
        for genre in genres:
            print(f"  - {genre}") # e.g., ['Crime', 'Drama', 'Thriller']
    else:
        print("  N/A")

    print("\nPlot Outline:")
    # Plot can be a list, let's take the first one if available
    plot_outline = full_movie.get('plot outline', 'N/A')
    if isinstance(plot_outline, list): # Sometimes plot is a list of strings
        plot_outline = plot_outline[0] if plot_outline else 'N/A'
    print(plot_outline[:200] + "..." if plot_outline != 'N/A' else 'N/A') # Print a snippet

    print("\nCast (Top 5):")
    cast = full_movie.get('cast', [])
    for i, person in enumerate(cast[:5]):
        # 'person' is a Person object. Access its 'name' attribute.
        print(f"  - {person.get('name', 'N/A')}") 
        # Example: Bryan Cranston, Anna Gunn, Aaron Paul ...

    print("\nProduction Companies (First 3):")
    companies = full_movie.get('production companies', [])
    for i, company in enumerate(companies[:3]):
        # 'company' is a Company object. Access its 'name' attribute.
        print(f"  - {company.get('name', 'N/A')}")
        # Example: High Bridge Productions, Gran Via Productions, Sony Pictures Television

    print("="*50)

    # Want to see EVERYTHING? The raw data is in `full_movie.data`
    print("\n--- Full Raw Data Example (all available fields for Breaking Bad) ---")
    # This is the complete data structure you can expect for a detailed movie/series.
    # Note: In a real script, you'd access specific keys rather than printing everything.
    # Below is an example of what `full_movie.data` would contain for "Breaking Bad":

{
 'akas': ['Rompiendo Tus Límites Morales (Spain)',
          '绝命毒师 (China, Mandarin title)',
          'ブレイキング・バッド (Japan, Japanese title)',
          'Kriva pota (Slovenia)',
          'Во все тяжкие (Russia)'],
 'aspect ratio': '1.78 : 1 (UHD)',
 'cast': ['<Person id:0186505[http] name:_Bryan Cranston_>',
          '<Person id:0348152[http] name:_Anna Gunn_>',
          '<Person id:0666739[http] name:_Aaron Paul_>',
          '<Person id:1336827[http] name:_Betsy Brandt_>',
          '<Person id:2666409[http] name:_RJ Mitte_>',
          '<Person id:0606487[http] name:_Dean Norris_>',
          '<Person id:0644022[http] name:_Bob Odenkirk_>',
          '<Person id:2366374[http] name:_Steven Michael Quezada_>',
          '<Person id:0052186[http] name:_Jonathan Banks_>',
          '<Person id:0002064[http] name:_Giancarlo Esposito_>',
          '<Person id:1889973[http] name:_Charles Baker_>',
          '<Person id:0687146[http] name:_Jesse Plemons_>',
          '<Person id:0184086[http] name:_Christopher Cousins_>',
          '<Person id:0292182[http] name:_Laura Fraser_>',
          '<Person id:2804503[http] name:_Matt Jones_>',
          '<Person id:0928795[http] name:_Michael Shamus Wiles_>',
          '<Person id:1089417[http] name:_Lavell Crawford_>',
          '<Person id:1530474[http] name:_Ray Campbell_>',
          '<Person id:1269983[http] name:_Krysten Ritter_>',
          '<Person id:0784831[http] name:_Carmen Serano_>',
          '<Person id:1986960[http] name:_Emily Rios_>',
          '<Person id:0662669[http] name:_Tina Parker_>',
          '<Person id:0546797[http] name:_Mark Margolis_>',
          '<Person id:0084497[http] name:_Jeremiah Bitsui_>',
          '<Person id:3970678[http] name:_Ian Posada_>',
          '<Person id:0182345[http] name:_David Costabile_>',
          '<Person id:0100889[http] name:_Michael Bowen_>',
          '<Person id:1450145[http] name:_David House_>',
          '<Person id:0710271[http] name:_Kevin Rankin_>',
          '<Person id:3718379[http] name:_Daniel Moncada_>',
          '<Person id:4577760[http] name:_Patrick Sane_>',
          '<Person id:5987281[http] name:_Moira Bryg MacDonald_>',
          '<Person id:0372961[http] name:_Jessica Hecht_>',
          '<Person id:0122987[http] name:_Bill Burr_>',
          '<Person id:2256387[http] name:_Marius Stan_>',
          '<Person id:2968788[http] name:_Rodney Rush_>',
          '<Person id:0856086[http] name:_Todd Terry_>',
          '<Person id:1616991[http] name:_Luis Moncada_>',
          '<Person id:3979839[http] name:_Kaija Bales_>',
          '<Person id:1324884[http] name:_Tait Fletcher_>',
          '<Person id:5597998[http] name:_Matthew T. Metzler_>',
          '<Person id:0190441[http] name:_Raymond Cruz_>',
          '<Person id:0002128[http] name:_Tess Harper_>',
          '<Person id:0209496[http] name:_John de Lancie_>',
          '<Person id:0122716[http] name:_Jere Burns_>',
          '<Person id:0316708[http] name:_Nigel Gibbs_>',
          '<Person id:0452622[http] name:_Tom Kiesche_>',
          '<Person id:0173997[http] name:_Maurice Compte_>',
          '<Person id:2813734[http] name:_Morse Bicknell_>',
          '<Person id:5518772[http] name:_Christopher King_>'],
 'certificates': ['Argentina:18',
                  'Australia:MA15+',
                  'Brazil:16',
                  'Brazil:14::(some episodes)',
                  'Bulgaria:D',
                  'Canada:14A',
                  'Canada:13+::(Québec)',
                  'Canada:14+::(TV Rating)',
                  'Chile:18',
                  'Colombia:15',
                  'Denmark:15::(DVD and Blu-ray rating)',
                  'Ecuador:16::(self-applied)',
                  'Egypt:18+::(self-applied)',
                  'Finland:K-16',
                  'France:Tous publics::(with warning)',
                  'Germany:16',
                  'Hong Kong:IIB',
                  'Hong Kong:16+::(self-applied)',
                  'Hungary:18',
                  'Iceland:16',
                  'India:18::(self-applied)',
                  'Indonesia:21+',
                  'Ireland:18::(some episodes, Season 1-2, 4-5 DVD)',
                  'Ireland:15::(some episodes, Season 3, 6 DVD)',
                  'Israel:16::(self-applied)',
                  'Italy:VM14::(self-applied)',
                  'Japan:R18+',
                  'Lithuania:N-16::(Netflix self-rating)',
                  'Mexico:C',
                  'Netherlands:16',
                  'New Zealand:R16::(most episodes, Season 1-3, 5-6 DVD)',
                  'New Zealand:M::(one episode)',
                  'New Zealand:R13::(some episodes)',
                  'New Zealand:R18::(some episodes, Season 4 DVD)',
                  'Norway:15::(DVD and Blu-ray rating)',
                  'Peru:18',
                  'Philippines:R-13::(Season 1-5, Part 1)',
                  'Philippines:R-16::(Season 5, Part 2)',
                  'Philippines:18+::(self-applied)',
                  'Poland:12',
                  'Portugal:M/16',
                  'Portugal:16',
                  'Russia:18+',
                  'Singapore:M18',
                  'Singapore:NC16::(final season)',
                  'South Africa:16',
                  'South Korea:19',
                  'Spain:16',
                  'Sweden:15::(DVD and Blu-ray rating)',
                  'Taiwan:15+',
                  'Thailand:20::(seasons 1-3)',
                  'Thailand:15::(seasons 4-5)',
                  'Turkey:18+::(self-applied)',
                  'United Kingdom:18',
                  'United Kingdom:15::(most episodes, Season 2-3, 5-6 DVD)',
                  'United Kingdom:12::(one episode)',
                  'United Kingdom:18::(some episodes, Season 1, 4 DVD)',
                  'United States:TV-MA',
                  'United States:TV-MA',
                  'United States:TV-14::(some episodes)',
                  'Ukraine:18',
                  'United Arab Emirates:18+::(self-applied)',
                  'Vietnam:C18'],
 'color info': ['Color'],
 'countries': ['United States'],
 'country codes': ['us'],
 'cover url': 'https://m.media-amazon.com/images/M/MV5BMzU5ZGYzNmQtMTdhYy00OGRiLTg0NmQtYjVjNzliZTg1ZGE4XkEyXkFqcGc@._V1_SX101_CR0,0,101,150_.jpg',
 'distributors': ['<Company id:0019701[http] name:_American Movie Classics (AMC)_>',
                  '<Company id:0340961[http] name:_5USA_>',
                  '<Company id:0164664[http] name:_ARTE_>',
                  '<Company id:0014456[http] name:_ARTE_>',
                  '<Company id:0014456[http] name:_ARTE_>',
                  '<Company id:0014456[http] name:_ARTE_>',
                  '<Company id:0195106[http] name:_AXN_>',
                  '<Company id:0195106[http] name:_AXN_>',
                  '<Company id:0254806[http] name:_AXN_>',
                  '<Company id:0337718[http] name:_Amazon Instant Video_>',
                  '<Company id:0196006[http] name:_BeTV_>',
                  '<Company id:0203432[http] name:_CNBC-e_>',
                  '<Company id:0984867[http] name:_Chili Cinema_>',
                  '<Company id:0429603[http] name:_Fiji Broadcasting_>',
                  '<Company id:0441319[http] name:_Film1 Action_>',
                  '<Company id:0365102[http] name:_Film1 Series_>',
                  '<Company id:0187155[http] name:_Five US_>',
                  '<Company id:0070925[http] name:_Fox Network_>',
                  '<Company id:0289973[http] name:_Fuji TV NEXT_>',
                  '<Company id:0879800[http] name:_Google Play_>',
                  '<Company id:0390640[http] name:_HD suisse_>',
                  '<Company id:0488997[http] name:_KVH Media Group_>',
                  '<Company id:0851917[http] name:_MagentaTV_>',
                  '<Company id:0916189[http] name:_Maxdome_>',
                  '<Company id:0131820[http] name:_Monte Carlo Televisión - Canal 4_>',
                  '<Company id:0982154[http] name:_NOW!_>',
                  '<Company id:0029644[http] name:_Nelonen_>',
                  '<Company id:0144901[http] name:_Netflix_>',
                  '<Company id:0144901[http] name:_Netflix_>',
                  '<Company id:0144901[http] name:_Netflix_>',
                  '<Company id:0225813[http] name:_Nova Cinema_>',
                  '<Company id:0204647[http] name:_ORF 1_>',
                  '<Company id:0308019[http] name:_Orange Cinémax_>',
                  '<Company id:0047950[http] name:_Paramount Comedy_>',
                  '<Company id:0131276[http] name:_Pop TV_>',
                  '<Company id:0304700[http] name:_Prime Series_>',
                  '<Company id:0005774[http] name:_RTL Klub Televízió_>',
                  '<Company id:0374655[http] name:_RTL Nitro_>',
                  '<Company id:0899200[http] name:_Rakuten TV_>',
                  '<Company id:0899200[http] name:_Rakuten TV_>',
                  '<Company id:0492252[http] name:_SRF zwei_>',
                  '<Company id:0015806[http] name:_Schweizer Fernsehen (SF)_>',
                  '<Company id:0137851[http] name:_Sony Pictures Home Entertainment_>',
                  '<Company id:0137851[http] name:_Sony Pictures Home Entertainment_>',
                  '<Company id:0137851[http] name:_Sony Pictures Home Entertainment_>',
                  '<Company id:0137851[http] name:_Sony Pictures Home Entertainment_>',
                  '<Company id:0137851[http] name:_Sony Pictures Home Entertainment_>',
                  '<Company id:0137851[http] name:_Sony Pictures Home Entertainment_>',
                  '<Company id:0137851[http] name:_Sony Pictures Home Entertainment_>',
                  '<Company id:0137851[http] name:_Sony Pictures Home Entertainment_>',
                  '<Company id:0137851[http] name:_Sony Pictures Home Entertainment_>',
                  '<Company id:0137851[http] name:_Sony Pictures Home Entertainment_>',
                  '<Company id:0137851[http] name:_Sony Pictures Home Entertainment_>',
                  '<Company id:0137851[http] name:_Sony Pictures Home Entertainment_>',
                  '<Company id:0137851[http] name:_Sony Pictures Home Entertainment_>',
                  '<Company id:0137851[http] name:_Sony Pictures Home Entertainment_>',
                  '<Company id:0137851[http] name:_Sony Pictures Home Entertainment_>',
                  '<Company id:0533814[http] name:_Spike_>',
                  '<Company id:0007113[http] name:_SundanceTV_>',
                  '<Company id:0203290[http] name:_Super! Drama TV_>',
                  '<Company id:0182488[http] name:_TV8_>',
                  '<Company id:0440561[http] name:_Universal Channel_>',
                  '<Company id:0375381[http] name:_Universal Sony Pictures Home Entertainment_>',
                  '<Company id:0362812[http] name:_Videoload_>',
                  '<Company id:0018439[http] name:_Vrijzinnig Protestantse Radio Omroep (VPRO)_>',
                  '<Company id:0598530[http] name:_e2_>',
                  '<Company id:0694131[http] name:_iTunes_>',
                  '<Company id:0044989[http] name:_Österreichischer Rundfunk (ORF)_>'],
 'genres': ['Crime', 'Drama', 'Thriller'],
 'imdbID': '0903747',
 'kind': 'tv series',
 'language codes': ['en', 'es'],
 'languages': ['English', 'Spanish'],
 'localized title': 'Breaking Bad',
 'number of seasons': 5,
 'original title': 'Breaking Bad',
 'other companies': ['<Company id:0223824[http] name:_Absolut Video_>',
                     '<Company id:0056883[http] name:_All Star Motion Picture Catering_>',
                     '<Company id:0300363[http] name:_BT Industrial Supply_>',
                     '<Company id:0008022[http] name:_Chapman/Leonard Studio Equipment_>',
                     '<Company id:0008022[http] name:_Chapman/Leonard Studio Equipment_>',
                     '<Company id:0012439[http] name:_Clairmont Camera Film & Digital_>',
                     '<Company id:0211783[http] name:_DTC Grip & Electric_>',
                     '<Company id:0594011[http] name:_Exchange Communications_>',
                     '<Company id:0244588[http] name:_Filmtools_>',
                     '<Company id:0184253[http] name:_Hear Kitty_>',
                     '<Company id:0076640[http] name:_Keep Me Posted_>',
                     '<Company id:0249155[http] name:_LCW Props_>',
                     '<Company id:0306663[http] name:_Madison Gate Records_>',
                     '<Company id:0306663[http] name:_Madison Gate Records_>',
                     '<Company id:0200641[http] name:_PES Payroll_>',
                     '<Company id:0009149[http] name:_Pacific Studios II_>',
                     '<Company id:0244989[http] name:_Pigfactory_>',
                     '<Company id:0709047[http] name:_Prop Movie Money_>',
                     '<Company id:0234319[http] name:_ReadySetMedic.com_>',
                     '<Company id:0208516[http] name:_Rockbottom Rentals_>',
                     '<Company id:0208516[http] name:_Rockbottom Rentals_>',
                     '<Company id:0208516[http] name:_Rockbottom Rentals_>',
                     '<Company id:0296749[http] name:_Scenechronize_>',
                     '<Company id:0029756[http] name:_Serious Grippage & Light_>',
                     '<Company id:0248241[http] name:_Sony Pictures Stock Footage_>',
                     '<Company id:0075800[http] name:_Soundtrack New York_>',
                     '<Company id:0845233[http] name:_Studio Concierge_>',
                     '<Company id:0136851[http] name:_The Domain Group_>',
                     '<Company id:0449838[http] name:_inVision Subtitling_>'],
 'plot': ['A chemistry teacher diagnosed with inoperable lung cancer turns to '
          'manufacturing and selling methamphetamine with a former student to '
          "secure his family's future.",
          'Walter White is a chemistry genius but works as a chemistry teacher '
          'at a high school in Albuquerque, New Mexico. His life drastically '
          "changes when he's diagnosed with stage III terminal lung cancer and "
          'given a prognosis of two years to live. To ensure that his pregnant '
          'wife and disabled teenage son have a financial future, he uses his '
          "chemistry background to create and sell the world's finest crystal "
          'methamphetamine. To sell his signature "blue meth," he teams up '
          'with Jesse Pinkman, a former student of his. The meth makes them '
          'very rich very quickly, but it attracts the attention of his DEA '
          "brother-in-law, Hank. As Walter and Jesse's status in the drug "
          'world escalates, Walter becomes a dangerous criminal, and Jesse '
          'becomes a hot-headed salesman. Hank is always hot on his tail, '
          'forcing Walter to devise new ways to cover his tracks.—halo1k, '
          'jackenyon',
          'A once-loyal father and chemistry teacher named Walter White turns '
          'to a life of crime due to developing Stage 3 terminal lung cancer. '
          'He has two years to live. Teaming up with one of his former '
          'students, Jesse Pinkman, he grows in power, battles anyone in his '
          'way, and raises a family - all while hiding from his '
          'brother-in-law, Hank, who works for the '
          'DEA.—joshchristian-142-732069'],
 'plot outline': 'Walter White is a chemistry genius but works as a chemistry '
                 'teacher at a high school in Albuquerque, New Mexico. His '
                 "life drastically changes when he's diagnosed with stage III "
                 'terminal lung cancer and given a prognosis of two years to '
                 'live. To ensure that his pregnant wife and disabled teenage '
                 'son have a financial future, he uses his chemistry '
                 "background to create and sell the world's finest crystal "
                 'methamphetamine. To sell his signature "blue meth," he teams '
                 'up with Jesse Pinkman, a former student of his. The meth '
                 'makes them very rich very quickly, but it attracts the '
                 'attention of his DEA brother-in-law, Hank. As Walter and '
                 "Jesse's status in the drug world escalates, Walter becomes a "
                 'dangerous criminal, and Jesse becomes a hot-headed salesman. '
                 'Hank is always hot on his tail, forcing Walter to devise new '
                 'ways to cover his tracks.',
 'production companies': ['<Company id:0212797[http] name:_High Bridge Productions_>',
                          '<Company id:0071947[http] name:_Gran Via Productions_>',
                          '<Company id:0086397[http] name:_Sony Pictures Television_>',
                          '<Company id:0019701[http] name:_American Movie Classics (AMC)_>'],
 'rating': 9.5,
 'runtimes': ['45'],
 'seasons': ['1', '2', '3', '4', '5'],
 'series years': '2008-2013',
 'sound mix': ['Dolby Digital'],
 'special effects': ['<Company id:0057238[http] name:_Velocity Visuals_>'],
 'synopsis': ['Season 1A struggling high school chemistry teacher, Walter '
              'White (Bryan Cranston), is diagnosed with inoperable, advanced '
              'lung cancer. On a ride along with his DEA agent brother-in-law '
              'Hank Schrader (Dean Norris), Walter sees a former student of '
              'his, Jesse Pinkman (Aaron Paul), fleeing the scene of a meth '
              'lab. He later contacts Jesse and devises a scheme to become '
              'partners in an attempt to combine their skills to manufacture '
              'and distribute methamphetamine, with Walter cooking the product '
              'and Jesse using his street connections to distribute it. Walter '
              'says he wants to provide financial stability for his pregnant '
              'wife, Skyler (Anna Gunn) and disabled son, and to pay for his '
              "expensive cancer treatment. During Walter and Jesse's first "
              "days of selling Albuquerque's finest meth, they encounter a "
              'series of problems with local drug dealers. Walter takes to '
              'selling the meth he produces to a local druglord, Tuco '
              "Salamanca (Raymond Cruz), using the alias \'Heisenberg\'.Season "
              '2Walter continues to find himself facing insurmountable medical '
              'bills from his cancer treatment. Despite having had several bad '
              'experiences while producing meth with Jesse, Walter agrees to '
              'rejoin his partner. The two begin producing meth but run into '
              "multiple problems. Jesse's friend Badger (Matt L. Jones) is "
              'arrested while selling meth in a sting operation. Walter hires '
              'a lawyer, Saul Goodman (Bob Odenkirk), to help Badger. Walter '
              'and Jesse drive a recreational vehicle into the desert and '
              "produce meth for four days. Later, Combo, another of Jesse's "
              'friends and distributors, is killed by a rival gang for selling '
              'meth in their territory. Saul suggests the two find a new '
              'distribution model. Throughout this, Jesse has been building a '
              'relationship with his neighbor and landlord, Jane Margolis '
              '(Krysten Ritter). Jane, who is a recovering addict, relapses '
              'and the two begin doing heroin. Saul finds them a new business '
              'partner, Gus Fring (Giancarlo Esposito), who is willing to pay '
              '$1.2 million for the 38 pounds of meth they produced. Walter '
              "hastily delivers the product to Gus, but misses his daughter's "
              "birth. Walt withholds Jesse's half of the money because of his "
              'drug use, but Jane finds out about it and blackmails Walt. Walt '
              "visits Jesse's house and witnesses Jane overdosing and choking "
              'on her own vomit, but perceiving her as an enemy, sits idly '
              'beside her and lets her die. Skyler confronts Walter about his '
              'frequent absences and excuses. She begins to piece together his '
              'secret life and demands that they separate.Season 3Walter '
              'wishes to reunite his family, but Skyler is still suspicious of '
              "Walter's second life. Walter believes he can mend the tension "
              'between them by confessing to her that he has been producing '
              'meth. Skyler is appalled by the confession and demands a formal '
              'divorce. Meanwhile, Gus offers to pay Walter $3M for three '
              'months of his service. He even offers to provide Walter with a '
              'state-of-the-art production facility and a brilliant lab '
              'assistant, Gale (David Costabile). Jesse is continuing to '
              'produce and sell meth by himself.Hank is working with the DEA '
              'to investigate Jesse and is slowly gathering evidence to make '
              "an arrest. He survives an assassination attempt made by Tuco's "
              'twin cousins and manages to kill one of his assailants and '
              'critically injure the other, who later dies in the hospital. '
              'Hank suffers critical wounds but survives.Jesse threatens to '
              'report Walter to the police if he is arrested, but Walter '
              "offers him Gale's position at the lab. After obtaining the "
              'position, Jesse begins stealing meth from the lab and selling '
              'it in secret on the side. Jesse gets romantically involved with '
              'a woman he meets in his rehab group and learns her kid brother, '
              'age 11, was put up by Gus and his street dealers to kill Combo. '
              'Jesse decides to avenge Combo. Walter aids Jesse in escaping '
              "from Gus's wrath. Gus begins to lose trust in Walter and asks "
              'Gale to take over the lab. He orders his henchmen to kill '
              'Walter and Jesse. After he is abducted by the henchmen, Walter '
              'instructs Jesse over the phone to kill Gale in order to force '
              'Gus not to kill Walter (and, by extension, Jesse) lest he '
              'eliminate his only remaining trained chemist.Season 4Jesse '
              "follows Walter's instructions and murders Gale. Gus decides to "
              'discipline the two by enforcing stricter policies at the lab. '
              "He also tries to break Walter and Jesse's friendship by "
              'assigning them to separate work details. While Walter works in '
              "the meth lab, Jesse escorts Mike (Jonathan Banks), one of Gus's "
              'enforcers, to retrieve payments and provide back-up. Walter and '
              'Jesse become increasingly distant from, and hostile to, each '
              'other. Meanwhile, Hank, who has been recovering from his last '
              'engagement with the cartel, finds evidence linking Gale to Gus. '
              'He believes Gus is a major drug distributor and starts looking '
              "for tangible evidence to file charges. Gus realizes Walter's "
              'close ties with Hank could jeopardize his entire operation. Gus '
              'fires Walter and informs him Hank will be killed. He also warns '
              'Walter that if he intervenes his entire family will be '
              'murdered. Jesse and Walter put their differences aside and '
              'agree to murder Gus, convincing former cartel enforcer Hector '
              'Salamanca to detonate a suicide bomb; Hector succeeds in this '
              "endeavor, killing himself, Gus, and Tyrus, Gus's henchman. "
              'Walter and Jesse then destroy the meth lab and Walter declares '
              'to his wife, "I won."Season 5Following Gus Fring\'s death, '
              'Walter partners with Jesse and Mike to create a new meth '
              'production and distribution operation. Mike handles all '
              'business aspects of the partnership, while Walter and Jesse '
              'work with a team of house fumigators to produce meth in tented '
              'houses. Hank and the DEA are able to identify nine prison '
              'inmates and one lawyer with criminal ties to Mike. Walter kills '
              "Mike, and is fearful that the informants will flip on Walter's "
              'operation since Mike is no longer able to pay them to keep '
              'quiet. He hires Jack Welker, the leader of a neo-Nazi gang, to '
              "kill the ten informants from within prison. Walter's business "
              'continues unimpeded until he decides to retire after accruing '
              '$80 million, which he buries in the desert.Later, Hank is '
              "invited to the Whites' home, where he unintentionally stumbles "
              "upon one of Walter's books with a signed message from Gale "
              'Boetticher. He realizes that Walter is the infamous Heisenberg '
              'and secretly restarts the investigation. Hank forms an alliance '
              'with Jesse, who now despises Walter for all his wrongdoings. '
              'Left with no options, Walter hires Jack again to murder Jesse. '
              'Walter attempts to confront Jesse in the desert, but instead '
              'Hank traps and arrests him. The neo-Nazi gang arrives and '
              'engages Hank in a fierce firefight. Jack executes Hank despite '
              "Walter's pleas. Jesse is captured and forced into slavery, "
              'producing meth for the gang. Before leaving, Jack and his gang '
              "take a majority of Walter's money, leaving him with only $11 "
              "million.Skyler and Walter Jr. are distraught over Hank's death "
              'and hold Walter accountable. They refuse to leave Albuquerque '
              'with Walter and instead contact the police. Walter spends the '
              'next several months hiding in a cabin in New Hampshire while '
              'struggling with cancer. He returns to New Mexico in order to '
              'visit his family one final time and seek revenge against Jack. '
              "Later that night, Walter executes all of the gang's members and "
              'frees Jesse, who escapes from the compound before the police '
              'arrive. Walter realizes he is mortally wounded from a gunshot '
              'and slowly succumbs to his injury as the police search the '
              'compound.'],
 'title': 'Breaking Bad',
 'videos': ['http://www.imdb.com/title/tt0903747/videoplayer/vi2624111385',
            'http://www.imdb.com/title/tt0903747/videoplayer/vi3743007513'],
 'votes': 2326262,
 'writer': ['<Person id:0319213[http] name:_Vince Gilligan_>',
            '<Person id:0319213[http] name:_Vince Gilligan_>',
            '<Person id:0332467[http] name:_Peter Gould_>'],
 'year': 2008
}

else:
    print("Run the previous cells to fetch movie details first.")

Key Data Fields You Can Expect

As seen with "Breaking Bad", imdbpy can fetch a vast amount of data. Here are some common and useful fields you'll often find in the full_movie.data dictionary:

Titles: title, original title, localized title, akas (Also Known As)
Identifiers: imdbID
Type & Year: kind (e.g., 'tv series', 'movie'), year, series years
Ratings: rating, votes
Media: cover url, videos
Details: runtimes, aspect ratio, sound mix, color info
Content: genres, plot (often a list), plot outline, synopsis
People & Companies:
- cast, writer, director (lists of Person objects; access names via person.get('name'))
- production companies, distributors, other companies, special effects (lists of Company objects; access names via company.get('name'))
Classification & Localization: certificates (e.g., 'United States:TV-MA'), countries, country codes, languages, language codes
For TV Series: number of seasons, seasons (list of season numbers)

The exact fields available can vary depending on how much information IMDb has for a particular title. Always use .get() with a default value or check if a key exists before accessing it directly to avoid errors.

Wrapping Up

imdbpy is a powerful yet straightforward library for accessing IMDb's rich database. We've covered:

Installation and setup.
Searching for titles.
Fetching comprehensive details using a movie ID.
Exploring the structure of the returned data, with "Breaking Bad" as our guide.

Now you have the tools to start building your own movie or TV show-related applications. Imagine the possibilities!

💬 Let's Discuss!

What cool projects are you thinking of building with IMDb data? Or what's your favorite obscure movie fact you've discovered? Share your thoughts and ideas in the comments below!

Happy coding!

Real-Time DonationAlerts Notifications with Python, OAuth & WebSockets 🚀

Fedor Pasynkov — Fri, 02 May 2025 20:53:53 +0000

Hey Devs! 👋

Ever wanted to react instantly when you receive a donation on DonationAlerts? Maybe trigger an effect in your stream, update a dashboard, or just log donations reliably without constantly hitting an API? Polling APIs works, but it's inefficient and not real-time.

DonationAlerts offers a way to get these notifications instantly using WebSockets, but setting it up involves navigating the OAuth 2.0 flow and their specific WebSocket protocol (powered by Centrifugo).

In this guide, we'll walk through how to:

Register an application on DonationAlerts.
Implement the OAuth 2.0 Authorization Code flow using Python (with FastAPI).
Connect to the DonationAlerts Centrifugo WebSocket.
Authenticate, subscribe, and receive real-time donation messages.
Understand the format of the donation data.

Let's ditch the polling and get those donations flowing in real-time!

Prerequisites

A DonationAlerts account (the streamer account you want to monitor).
Python 3.8+ installed.
Basic familiarity with Python. FastAPI knowledge is helpful but not strictly required to understand the concepts.
pip for installing packages.

(We'll use FastAPI for the web server handling OAuth, but the core logic for interacting with DonationAlerts API and WebSockets can be adapted to other frameworks.)

Step 1: Register Your App on DonationAlerts 🔑

Before we write any code, we need to tell DonationAlerts about our application and get some credentials.

Go to the DonationAlerts OAuth Applications page: https://www.donationalerts.com/application/clients
Log in using your streamer account (Twitch, YouTube, etc.).
On the "OAuth API Applications" page, click the "+ CREATE NEW APP" button.
Fill in the "New Application" form:
- App name: Give it a descriptive name, like "My Realtime Monitor". (This is shown to users).
- Redirect URL: This is CRUCIAL. Enter the exact URL where DonationAlerts will send the user back after they authorize your app. For local development with our example, use: http://localhost:8000/api/auth/donationalerts/callback. If you deploy, this needs to be your public callback URL.
Click the orange "CREATE" button.
Find your newly created app in the list. You'll need two pieces of information:
- App ID: This is your unique application identifier. We'll call it APP_ID.
- API Key: This is your application's secret. Keep this safe and never expose it in frontend code! We'll call it API_KEY.

Copy these two values (APP_ID and API_KEY). We'll need them soon.

Step 2: Understanding the OAuth 2.0 Flow 🌊

We need the user (the streamer) to grant our application permission to access their data (specifically, view their profile and subscribe to donation events) without giving us their password. That's where OAuth 2.0 comes in. We'll use the "Authorization Code" flow, which is standard for web applications.

Here's the gist:

User Initiates: The user clicks a "Login with DonationAlerts" button in our app.
Redirect to DonationAlerts: Our backend redirects the user's browser to a special DonationAlerts URL, including our APP_ID, the requested scopes (permissions), and the redirect_uri.
User Authorizes: The user logs into DonationAlerts (if needed) and sees a screen asking them to approve the permissions our app requested (oauth-user-show, oauth-donation-subscribe).
Redirect Back with Code: If approved, DonationAlerts redirects the user's browser back to our redirect_uri, adding a temporary code to the URL.
Exchange Code for Token: Our backend receives this code, verifies it, and then securely makes a server-to-server request to DonationAlerts, sending the code, our APP_ID, and our secret API_KEY.
Receive Tokens: DonationAlerts verifies everything and sends back an access_token (used to make API calls) and a refresh_token (used to get a new access_token when the old one expires).

This access_token is the key to interacting with the DonationAlerts API on the user's behalf.

Step 3: Implementing OAuth in Python (FastAPI Example) 🐍

Let's set up a simple FastAPI app to handle this flow.

(For a full runnable example including token storage, WebSocket management, and an interactive setup helper, check out the code in the donationalerts-oauth-websocket-example repository.)

Configuration (config.py / .env)

It's best practice to store credentials and settings outside your code. We can use a .env file and a helper config.py module (as shown in the full example) to load these. Your .env would look like this:

# .env
APP_ID="YOUR_APP_ID_HERE"
API_KEY="YOUR_API_KEY_HERE"
REDIRECT_URI="http://localhost:8000/api/auth/donationalerts/callback"
SESSION_SECRET_KEY="GENERATE_A_STRONG_RANDOM_KEY_HERE" # For session security

# Usually fixed
DA_SCOPES="oauth-user-show oauth-donation-subscribe"
DA_AUTHORIZATION_URL="https://www.donationalerts.com/oauth/authorize"
DA_TOKEN_URL="https://www.donationalerts.com/oauth/token"
DA_API_BASE_URL="https://www.donationalerts.com/api/v1"
# ... other URLs if needed

FastAPI Endpoints (main.py)

We need two main endpoints: one to start the login, and one to handle the callback.

# main.py (Simplified Snippets)
import httpx
import secrets
from fastapi import FastAPI, Request, Depends
from fastapi.responses import RedirectResponse
from starlette.middleware.sessions import SessionMiddleware # For storing state

# Assume 'settings' is loaded from config.py or .env
# settings = load_app_config() # From our full example's config.py

app = FastAPI()

# IMPORTANT: SessionMiddleware is needed to store the OAuth state temporarily
app.add_middleware(SessionMiddleware, secret_key=settings["SESSION_SECRET_KEY"])

# --- Login Endpoint ---
@app.get("/api/auth/donationalerts/login")
async def login_donationalerts(request: Request):
    state = secrets.token_urlsafe(16)
    request.session['oauth_state'] = state # Store state to prevent CSRF

    params = {
        "client_id": settings["APP_ID"],
        "redirect_uri": settings["REDIRECT_URI"],
        "response_type": "code",
        "scope": settings["DA_SCOPES"],
        "state": state,
    }
    auth_request = httpx.Request('GET', settings["DA_AUTHORIZATION_URL"], params=params)
    authorization_url = str(auth_request.url)

    print(f"Redirecting to: {authorization_url}") # For debugging
    return RedirectResponse(authorization_url)

# --- Callback Endpoint ---
@app.get("/api/auth/donationalerts/callback")
async def auth_donationalerts_callback(request: Request, code: str = None, state: str = None, error: str = None):
    if error:
        # Handle authorization error from DonationAlerts
        return {"error": error}

    # --- Security Check: Verify State ---
    stored_state = request.session.pop('oauth_state', None)
    if not state or state != stored_state:
        # State mismatch, potential CSRF attack!
        return {"error": "Invalid state"}

    if not code:
        return {"error": "Missing authorization code"}

    # --- Exchange Code for Tokens ---
    token_data = await exchange_code_for_token(code) # See function below

    if not token_data:
        return {"error": "Failed to exchange code for token"}

    # --- Success! Store Tokens Securely ---
    # In a real app: save token_data['access_token'], token_data['refresh_token'],
    # and calculate token_data['expires_at'] in a database linked to the user.
    # For this example, we might use a simple file storage (like token_storage.py).
    # save_token(token_data) # From our full example's token_storage.py

    print("OAuth successful, tokens obtained!")
    # Redirect user back to the main page of your app
    return RedirectResponse(url="/?status=success", status_code=303)

# --- Helper: Token Exchange ---
async def exchange_code_for_token(code: str):
    data = {
        "grant_type": "authorization_code",
        "client_id": settings["APP_ID"],
        "client_secret": settings["API_KEY"],
        "code": code,
        "redirect_uri": settings["REDIRECT_URI"],
    }
    async with httpx.AsyncClient() as client:
        try:
            response = await client.post(settings["DA_TOKEN_URL"], data=data)
            response.raise_for_status() # Check for HTTP errors
            print("Token exchange successful!")
            return response.json()
        except httpx.HTTPStatusError as e:
            print(f"Token exchange failed: {e.response.status_code} - {e.response.text}")
            return None
        except Exception as e:
            print(f"An error occurred during token exchange: {e}")
            return None

This handles the core OAuth flow. Remember to securely store the obtained access_token and refresh_token.

Step 4: Connecting to the WebSocket (Centrifugo) 🕸️

Now that we have an access_token, we can connect to the WebSocket for real-time events. This is where it gets a bit tricky, as it involves three different types of tokens:

OAuth access_token: The one we just obtained. Needed for API calls.
socket_connection_token: A temporary token specifically for authenticating the WebSocket connection itself. We get this from the /api/v1/user/oauth API endpoint using our access_token.
subscription_token: Another temporary token needed to subscribe to a specific private channel (like the donations channel) after the WebSocket is authenticated. We get this from the /api/v1/centrifuge/subscribe endpoint using our access_token and a client_id provided by the WebSocket upon authentication.

The Connection Sequence:

Here's the sequence implemented in our example's donationalerts_client.py:

# donationalerts_client.py (Simplified Snippets)
import websockets
import json
import httpx

# Assume 'settings' is loaded, and we have a valid 'access_token'
# Also assume '_make_api_request' is a helper function using httpx and access_token

async def connect_and_listen():
    # --- Stage 1: Get User ID and Socket Token (HTTP API) ---
    try:
        user_info_response = await _make_api_request('GET', '/user/oauth', access_token)
        if not user_info_response or 'data' not in user_info_response:
             print("Failed to get user info")
             return
        user_id = user_info_response['data'].get('id')
        socket_token = user_info_response['data'].get('socket_connection_token')
        if not user_id or not socket_token:
            print("Missing user_id or socket_token in API response")
            return
    except Exception as e:
        print(f"Error getting user info/socket token: {e}")
        return

    print(f"Got User ID: {user_id}, Socket Token: {socket_token[:10]}...") # Don't log full token

    # --- Stage 2: Connect and Authenticate WebSocket ---
    websocket_url = settings["DA_CENTRIFUGO_URL"]
    try:
        async with websockets.connect(websocket_url) as ws:
            print(f"Connected to WebSocket: {websocket_url}")

            # --- Stage 2a: Send Socket Token ---
            # IMPORTANT: The format is specific! {"params": {"token": ...}, "id": 1}
            auth_payload = {"params": {"token": socket_token}, "id": 1}
            await ws.send(json.dumps(auth_payload))
            print("Sent WebSocket authentication request.")

            # --- Stage 2b: Receive Auth Response & Client ID ---
            auth_response_str = await ws.recv()
            auth_response = json.loads(auth_response_str)
            print(f"Received auth response: {auth_response}")

            client_id = None
            if auth_response.get("id") == 1 and auth_response.get("result", {}).get("client"):
                client_id = auth_response["result"]["client"]
                print(f"WebSocket authenticated! Client ID: {client_id}")
            else:
                print("WebSocket authentication failed!")
                return

            # --- Stage 3: Get Subscription Token (HTTP API) ---
            channel_name = f"$alerts:donation_{user_id}"
            sub_token_payload = {"client": client_id, "channels": [channel_name]}
            try:
                sub_response = await _make_api_request('POST', '/centrifuge/subscribe', access_token, json=sub_token_payload)
                if not sub_response or "channels" not in sub_response:
                     print("Failed to get subscription token response")
                     return

                subscription_token = None
                for channel_info in sub_response.get("channels", []):
                    if channel_info.get("channel") == channel_name and "token" in channel_info:
                        subscription_token = channel_info["token"]
                        break

                if not subscription_token:
                     print(f"Subscription token for {channel_name} not found in response.")
                     return

                print(f"Got Subscription Token: {subscription_token[:10]}...")
            except Exception as e:
                print(f"Error getting subscription token: {e}")
                return

            # --- Stage 4: Subscribe to Channel (WebSocket) ---
            subscribe_payload = {
                "id": 2, # Use a new ID for this request
                "method": 1, # 1 = subscribe
                "params": {"channel": channel_name, "token": subscription_token}
            }
            await ws.send(json.dumps(subscribe_payload))
            print(f"Sent subscribe request for channel {channel_name}")

            # --- Stage 5: Listen for Messages ---
            print("Waiting for donation messages...")
            async for message_str in ws:
                print(f"RAW MESSAGE RECEIVED: {message_str}")
                # Now parse the message (see next step)
                # handle_donation_message(message_str) 

    except websockets.exceptions.ConnectionClosedOK:
        print("WebSocket connection closed normally.")
    except Exception as e:
        print(f"WebSocket Error: {e}")

# --- Helper for API Requests (Example) ---
async def _make_api_request(method, endpoint, token, **kwargs):
     headers = {"Authorization": f"Bearer {token}"}
     url = f"{settings['DA_API_BASE_URL']}{endpoint}"
     async with httpx.AsyncClient() as client:
         response = await client.request(method, url, headers=headers, **kwargs)
         response.raise_for_status()
         return response.json()

Phew! That's the most complex part. Getting this sequence right is key.

Step 5: Handling Donation Messages 📨

Once subscribed, DonationAlerts will push messages through the WebSocket without an id field. The actual donation data is nested inside.

Message Format:

Based on observations, a typical donation message looks like this:

{
  "result": {
    "channel": "$alerts:donation_YOUR_USER_ID",
    "data": {
      "seq": 15, // Sequence number from Centrifugo
      "data": {
        // ---> THIS is the actual donation object <---
        "id": 164405432, // Unique Donation ID! Important for deduplication.
        "name": "DonatorName", // Name entered by donator (fallback)
        "username": "DonatorDA_Username", // DA username if logged in, else null
        "message": "Your message here! \r\n Can contain newlines.",
        "message_type": "text",
        "amount": 22.0,
        "currency": "USD",
        "is_shown": 1, // If shown in standard DA widgets
        "amount_in_user_currency": 1500.0,
        "recipient_name": "YourStreamerName",
        "recipient": { // Info about the recipient (you)
            "user_id": YOUR_USER_ID,
            "code": "YourStreamerLogin",
            "name": "YourStreamerName",
            "avatar": "URL_to_avatar"
         },
        "created_at": "2025-04-12 07:15:49" // Server time
        // ... potentially other fields ...
      }
    }
  }
}

Parsing in Python:

def handle_donation_message(message_str):
    try:
        message = json.loads(message_str)
        # Check if it's a push message (no 'id') and has the expected structure
        if "id" not in message and "result" in message:
            result_data = message.get("result", {})
            outer_data = result_data.get("data", {})
            donation_data = outer_data.get("data") # The actual donation payload

            if donation_data and result_data.get("channel", "").startswith("$alerts:donation_"):
                # Extract useful fields (use .get for safety)
                donation_id = donation_data.get("id")
                sender = donation_data.get("username") or donation_data.get("name", "Anonymous")
                amount = donation_data.get("amount")
                currency = donation_data.get("currency")
                text = donation_data.get("message", "")
                created_at = donation_data.get("created_at")

                print("-" * 20)
                print(f"🎉 New Donation! (ID: {donation_id})")
                print(f"   From: {sender}")
                print(f"   Amount: {amount} {currency}")
                print(f"   Message: {text.strip()}") # Strip whitespace/newlines
                print(f"   Time: {created_at}")
                print("-" * 20)

                # --- TODO: Send this data to your frontend or trigger actions! ---
                # Example: await websocket_manager.broadcast({"type": "donation", "data": donation_data})

            elif result_data.get("channel", "").startswith("$alerts:donation_"):
                 # Might be a subscribe confirmation or other message on the channel
                 print(f"Received non-donation push on channel: {message}")

        elif "id" in message:
             # This is likely an ack for one of our requests (id: 1 or 2) or a ping
             print(f"Received message with ID: {message}")
        else:
             print(f"Received unhandled message format: {message}")

    except json.JSONDecodeError:
        print(f"Error decoding JSON: {message_str}")
    except Exception as e:
        print(f"Error handling message: {e}")

# Inside the WebSocket listening loop:
# async for message_str in ws:
#     handle_donation_message(message_str)

Remember to handle potential missing fields gracefully using .get(). The id field is crucial if you want to prevent processing the same donation multiple times (DonationAlerts might occasionally send duplicates).

(Optional) Step 6: Displaying Donations 🖥️

The Python code above just prints the donation. To show it in a web interface, you'd typically use another WebSocket connection between your backend and your frontend.

Backend (websocket_manager.py / main.py): When handle_donation_message processes a donation, instead of printing, use a WebSocketManager to broadcast the donation_data to all connected frontend clients.
Frontend (index.html / JavaScript): Establish a WebSocket connection to your backend (/ws). Listen for messages. When a message of type: "donation" arrives, use JavaScript to parse the data and append it to the HTML.

// Simplified Frontend JS Example
let ws = new WebSocket(`ws://${window.location.host}/ws`); // Connect to your backend WS

ws.onmessage = function(event) {
    try {
        const message = JSON.parse(event.data);
        if (message.type === 'donation' && message.data) {
            // Function to add the donation to the page
            displayDonation(message.data); 
        }
    } catch (e) {
        console.error("Error processing message from backend:", e);
    }
};

function displayDonation(donation) {
    const log = document.getElementById('donations-log');
    const item = document.createElement('div');
    const sender = donation.username || donation.name || 'Anonymous';
    item.innerHTML = `<strong>${sender}</strong> donated ${donation.amount} ${donation.currency}: ${donation.message || ''}`;
    log.appendChild(item);
}

Conclusion ✨

We've covered the essential steps to receive real-time DonationAlerts notifications using OAuth 2.0 and WebSockets with Python. It involves setting up an app, handling the multi-step OAuth and WebSocket connection process (including those tricky specific tokens!), and parsing the incoming donation messages.

While the setup is more involved than simple polling or the older widget token method, it gives you a standard, robust way to integrate directly with the DonationAlerts event stream.

DEV Community: Fedor Pasynkov

How To Control Brightness In Ubuntu 22.04?

What We'll Build

Prerequisites

Step 1: Install brightnessctl

Step 2: Create the Brightness Control Script

Step 3: Make the Script Executable

Step 4: Test the Script

Step 5: Handle Sudo Requirements

Step 6: Set Up Automation with Cron

Step 7: Monitor the Script

Understanding the Brightness Calculation

Evening Transition (17:00-23:59)

Morning Transition (07:00-08:59)

Customization Options

Adjust Time Ranges

Adjust Brightness Levels

Change Update Frequency

Troubleshooting

Script Not Running

Brightness Not Changing

Permission Issues

Conclusion

Ready Script

How to Make Your Linux Laptop Auto-Shutdown and Show Notifications Based on Battery Level?

🎯 What This Script Does

📋 Prerequisites

System Requirements

Required Packages

🚀 Step 1: Project Setup

🔧 Step 2: Create Configuration File

🔐 Important Security Notes:

🔍 Finding Your Battery Path:

🎵 Getting a Notification Sound:

📝 Step 3: Create the Main Script

🔧 Step 4: Make Script Executable

🧪 Step 5: Test the Script

Manual Testing:

Test Different Scenarios:

⏰ Step 6: Automate with Cron

Edit your crontab:

Verify Cron Job:

📊 What the Script Logs

🛡️ Security Note

🎯 Configuration Tips

🚀 Conclusion

Setting Up Tailwind CSS v4 in SvelteKit: The Vite Plugin Way (A Guide Based on Real Issues)

Prerequisites

1. Creating Your SvelteKit Project with Tailwind CSS Integration (via npx sv create .)

2. Verifying Installed Packages for a Smooth Tailwind v4 Setup in SvelteKit

3. Step-by-Step: Configuring SvelteKit's Vite Setup for Tailwind CSS v4

4. Importing Tailwind CSS v4 in Your Main SvelteKit CSS File

5. Mastering Tailwind CSS v4 Theme Configuration in SvelteKit

6. Effectively Using Tailwind CSS v4 in Svelte Components (<style> blocks)

7. Key General v4 Changes and Recommendations for SvelteKit Developers

Conclusion and Next Steps

Twitch OAuth2 Explained for twitchio Bots: Getting Authorized

What is OAuth 2.0 and Why Do You Need It?

Table of Contents

Prerequisites

Step 1: Registering Your Application on the Twitch Developer Portal

Getting Your Client ID and Client Secret

Step 2: Defining Necessary Permissions (Scopes)

Step 3: Preparing for Authorization

Step 4: Constructing the Authorization URL

Step 5: Authorizing the Application and Obtaining the Code

Step 6: Exchanging the Authorization Code for Tokens (Access & Refresh)

Using curl to Exchange the Code for Tokens

Step 7: Storing Your Tokens Securely

Step 8: Validating Your Access Token (Recommended)

Step 9: Refreshing the Access Token

Wrapping Up and Next Steps

🎬 Movie Magic with Python: Your First Steps into IMDb Data using imdbpy

Who is this for?

🛠️ Setting Up: Installation and Initialization

🔎 Searching for Titles

🎬 Getting the Full Scoop: Fetching Detailed Information

📊 Accessing the Data: What's Inside?

Key Data Fields You Can Expect

Wrapping Up

1. Creating Your SvelteKit Project with Tailwind CSS Integration (via `npx sv create .`)

6. Effectively Using Tailwind CSS v4 in Svelte Components (`<style>` blocks)

Using `curl` to Exchange the Code for Tokens