Update cpulimiter library to version 1.5.0 with enhanced features and examples

ahmed0x77 · ahmed0x77 · commit 1456b1233c01 · 2025-07-05T09:55:54.000+02:00
- Refactor CpuLimiter to allow initialization with processes to limit.
- Update README with detailed usage instructions and examples.
- Modify MANIFEST.in to include necessary files.
- Add new example scripts demonstrating basic usage and simple limits.
- Improve setup.py with updated metadata and description.
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1,4 +1,4 @@
 include README.md
 include LICENSE
-include pyproject.toml
+recursive-include examples *.py
 recursive-include cpulimiter *.py
diff --git a/README.md b/README.md
@@ -1,56 +1,73 @@
 # cpulimiter 🚀
 
-A Python library for Windows to limit the CPU usage of running processes.
+[![PyPI version](https://img.shields.io/pypi/v/cpulimiter.svg)](https://pypi.org/project/cpulimiter/)
+[![PyPI pyversions](https://img.shields.io/pypi/pyversions/cpulimiter.svg)](https://pypi.org/project/cpulimiter/)
+[![PyPI license](https://img.shields.io/pypi/l/cpulimiter.svg)](https://github.com/Ahmed-Ashraf-dv/CPULimiter/blob/main/LICENSE)
 
-## Features ✨
+A simple, lightweight Python library for Windows to limit the CPU usage of any running process. Reduce CPU load, save power, and prevent overheating.
 
-- 🎯 Limit process CPU usage by a specified percentage.
-- 🔍 Target processes by Process ID (PID), executable name, or window title.
-- 🤝 Manage and control multiple limited processes simultaneously.
-- 🛠️ Utility functions to discover running and active processes.
+## 🤔 Why cpulimiter?
 
-## Installation 📦
+Have you ever had a program like `Google Chrome`, a game, or a background task consume 100% of your CPU, making your system unresponsive and your fans spin like a jet engine?
+
+`cpulimiter` solves this by throttling the application, allowing you to specify exactly how much CPU it can use. This is perfect for:
+
+- 🎮 Capping the CPU usage of games to prevent overheating.
+- 🌐 Limiting resource-hungry browsers like Chrome or Edge when running multiple tabs.
+- 💼 Running heavy data processing or video encoding tasks in the background without slowing down your machine.
+- 🔋 Saving battery life on laptops by reducing the power consumption of demanding applications.
+- 🤫 Quieting down noisy CPU fans.
+
+
+## ✨ Features
+
+- 🎯 **Limit CPU Usage:** Throttle process CPU usage to a specific percentage.
+- 🔍 **Flexible Targeting:** Target processes by Process ID (PID), executable name (`"chrome.exe"`), or even window title.
+- 🤝 **Multi-Process Management:** Control and limit multiple processes at the same time.
+- 🛠️ **Process Discovery:** Includes utility functions to find running applications and the active foreground window.
+- 🕊️ **Lightweight:** Has a minimal performance footprint and no external dependencies.
+
+## 📦 Installation
 
 ```bash
 pip install cpulimiter
 ```
 
-## Quick Start 📖
+## 📖 Quick Start
 
-The following example demonstrates how to limit `chrome.exe` to 5% of CPU usage (a 95% limit).
+The following example limits all `chrome.exe` processes to just 5% of a single CPU core's power (a 95% limit).
 
 ```python
 from cpulimiter import CpuLimiter
 import time
 
-# 1. Initialize the limiter
-limiter = CpuLimiter()
-
-# 2. Add the process directly by its name.
-# The library will find the PID for "chrome.exe" for you.
-limiter.add(process_name="chrome.exe", limit_percentage=95)
-
-# 3. Start the limit
-# You can also start it by name.
-print("Limiting Chrome for 15 seconds...")
-limiter.start(process_name="chrome.exe")
+# 1. Find all "chrome.exe" processes and limit them to 5% CPU.
+# The limit is a percentage (0-100). 95 means "limit by 95%", so it can only use 5%.
+limiter = CpuLimiter({"chrome.exe": 95})
 
+# 2. The limiter is now running in the background.
+# Let's keep it running for 15 seconds to see the effect.
+print("Limiting Chrome's CPU usage for 15 seconds...")
 time.sleep(15)
 
-# 4. Stop the limit
-print("Stopping limit.")
-limiter.stop(process_name="chrome.exe")
-print("Process limit removed.")
+# 3. To stop limiting, simply call the shutdown() method.
+limiter.shutdown()
+print("CPU limit removed. Chrome is back to normal.")
 ```
+*You can check your Task Manager to see the effect in real-time!*
+
+## ⚙️ How It Works
 
-## Examples 📚
+`cpulimiter` works by rapidly suspending and resuming the threads of a target process. For example, to achieve a 50% CPU limit, the library suspends the process for 10 milliseconds and then resumes it for 10 milliseconds, effectively cutting its CPU time in half. This cycle is managed by a lightweight, high-precision background thread.
 
-Check out the `examples/` folder for different use cases:
+## 📚 Examples
 
-- **`basic_usage.py`** - Simple introduction to the library
-- **`simple_limit.py`** - Manually limit specific applications
-- **`cpu_saver.py`** - Automatic CPU saver that limits all background apps
-- **`advanced_interactive.py`** - Interactive mode with real-time control
+Check out the `examples/` folder for more advanced use cases:
+
+- **`basic_usage.py`** - A simple, manual introduction to the library's methods.
+- **`simple_limit.py`** - Manually limit a list of specific applications.
+- **`cpu_saver.py`** - An automatic CPU saver that throttles all applications that are not in the foreground.
+- **`advanced_interactive.py`** - An interactive command-line tool for real-time process management.
 
 ## API Reference
 
@@ -91,4 +108,12 @@ Returns a dictionary containing the `pid`, `name`, and `title` of the foreground
 
 #### `get_active_app_pids()`
 
-Returns a dictionary of all processes with visible windows.
+Returns a dictionary of all processes with visible windows, mapping their PIDs to their executable names.
+
+## 🤝 Contributing
+
+Contributions, issues, and feature requests are welcome! Feel free to check the [issues page](https://github.com/Ahmed-Ashraf-dv/CPULimiter/issues).
+
+## 📜 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
diff --git a/cpulimiter/__init__.py b/cpulimiter/__init__.py
@@ -1,11 +1,11 @@
 """
-CPU Limiter
-A Python library to limit the CPU usage of processes.
+cpulimiter - A simple, lightweight Python library for Windows to limit CPU usage of processes.
 """
 
-__version__ = "1.0.0"
+__version__ = "1.5.0"
+__author__ = "Ahmed Ashraf"
 
 from .limiter import CpuLimiter
-from .utils import get_active_app_pids, get_active_window_info
+from .utils import get_active_window_info, get_active_app_pids
 
-__all__ = ["CpuLimiter", "get_active_app_pids", "get_active_window_info"], get_active_window_info
+__all__ = ["CpuLimiter", "get_active_window_info", "get_active_app_pids"]
diff --git a/cpulimiter/limiter.py b/cpulimiter/limiter.py
@@ -116,9 +116,30 @@ def _limit_loop(self):
 
 class CpuLimiter:
     """Manages and applies CPU limits to one or more processes."""
-    def __init__(self):
-        self._limiters = {}  # Stores {_ProcessLimiter object}
-        self._process_info = {} # Stores info about the processes being limited
+    def __init__(self, processes_to_limit: dict = None):
+        """
+        Initializes the CpuLimiter.
+
+        Args:
+            processes_to_limit (dict, optional): A dictionary where keys are process identifiers
+                                                 (name, pid, or window title part) and values are
+                                                 the limit percentage. If provided, automatically
+                                                 adds and starts limiting these processes.
+                                                 Example: {"chrome.exe": 95, 1234: 90}
+        """
+        self._limiters = {}  # Stores {pid: _ProcessLimiter object}
+        self._process_info = {} # Stores {pid: info dict}
+
+        if processes_to_limit:
+            for identifier, limit in processes_to_limit.items():
+                # Determine the type of identifier and call add() accordingly
+                if isinstance(identifier, int): # PID
+                    self.add(pid=identifier, limit_percentage=limit)
+                elif isinstance(identifier, str) and (identifier.endswith(".exe") or "." in identifier): # Process Name
+                    self.add(process_name=identifier, limit_percentage=limit)
+                elif isinstance(identifier, str): # Window Title
+                    self.add(window_title_contains=identifier, limit_percentage=limit)
+            self.start_all()
 
     def _find_pids_by_name(self, process_name):
         pids = []
@@ -162,6 +183,15 @@ def add(self, pid=None, process_name=None, window_title_contains=None, limit_per
                 }
                 self._limiters[p] = _ProcessLimiter(p, limit_percentage)
 
+    def remove(self, pid=None, process_name=None, window_title_contains=None):
+        """Removes a process from the limiter."""
+        pids_to_remove = self._get_pids_for_criteria(pid, process_name, window_title_contains)
+        for p in pids_to_remove:
+            if p in self._limiters:
+                self._limiters[p].stop()
+                del self._limiters[p]
+                del self._process_info[p]
+
     def start(self, pid=None, process_name=None, window_title_contains=None):
         """Starts limiting a specific process/group that has been added."""
         pids_to_start = self._get_pids_for_criteria(pid, process_name, window_title_contains)
@@ -186,6 +216,10 @@ def stop_all(self):
         for limiter in self._limiters.values():
             limiter.stop()
 
+    def shutdown(self):
+        """A convenient alias for stop_all()."""
+        self.stop_all()
+
     def get_active(self):
         """Returns a list of actively limited processes."""
         return [info for pid, info in self._process_info.items() if self._limiters[pid].active]
@@ -202,3 +236,4 @@ def _get_pids_for_criteria(self, pid=None, process_name=None, window_title_conta
             if window_title_contains and info["window_title_contains"] == window_title_contains:
                 found_pids.append(p)
         return found_pids
+
diff --git a/examples/basic_usage.py b/examples/basic_usage.py
@@ -1,43 +1,29 @@
 from cpulimiter import CpuLimiter
 import time
-import psutil
 
-def find_pid_by_name(process_name):
-    """Helper function to find a PID by its name."""
-    for proc in psutil.process_iter(['pid', 'name']):
-        if proc.info['name'] == process_name:
-            return proc.info['pid']
-    return None
 
 # --- Example Usage ---
 
 # 1. Initialize the limiter
 limiter = CpuLimiter()
 
-# 2. Find a process to limit (e.g., Notepad)
-#    (You can open Notepad to test this)
-notepad_pid = find_pid_by_name("notepad.exe")
+app_name = "notepad.exe"
 
-if notepad_pid:
-    print(f"Found Notepad with PID: {notepad_pid}")
+# 3. Add the process to the limiter
+limiter.add(process_name=app_name, limit_percentage=95)
 
-    # 3. Add the process to the limiter
-    limiter.add(pid=notepad_pid, limit_percentage=95)
+# 4. Start limiting
+print("Starting to limit Notepad for 15 seconds...")
+limiter.start(process_name=app_name)
 
-    # 4. Start limiting
-    print("Starting to limit Notepad for 15 seconds...")
-    limiter.start(pid=notepad_pid)
+# You can check the task manager to see the effect.
+time.sleep(15)
 
-    # You can check the task manager to see the effect.
-    time.sleep(15)
+# 5. Stop limiting
+print("Stopping the limit.")
+limiter.stop(process_name=app_name)
 
-    # 5. Stop limiting
-    print("Stopping the limit.")
-    limiter.stop(pid=notepad_pid)
-
-    print("Limiting has been stopped.")
-else:
-    print("Notepad is not running. Please open it and run the script again.")
+print("Limiting has been stopped.")
 
 # --- Example with multiple processes ---
 
diff --git a/examples/simple_limit.py b/examples/simple_limit.py
@@ -16,65 +16,58 @@
 def main():
     print("🚀 Simple CPU Limiter Example")
     print("=" * 40)
-    
-    # Initialize the limiter
-    limiter = CpuLimiter()
-    
-    # Add applications to limit
-    # This will find all running instances and limit them
-    print("📝 Adding applications to limit...")
-    
-    # Limit Chrome to 10% CPU (90% limitation)
-    limiter.add(process_name="chrome.exe", limit_percentage=90)
-    print("   ✅ Added Chrome (chrome.exe) - 90% limitation")
-    
-    # Limit Spotify to 5% CPU (95% limitation) 
-    limiter.add(process_name="spotify.exe", limit_percentage=95)
-    print("   ✅ Added Spotify (spotify.exe) - 95% limitation")
-    
-    # You can also limit by window title
-    limiter.add(window_title_contains="YouTube", limit_percentage=85)
-    print("   ✅ Added YouTube windows - 85% limitation")
-    
-    print("\n🔄 Starting CPU limiting...")
+
+    # With the updated library, you can define and start the limits all in one step.
+    # The keys are the process identifiers (name, PID, or window title substring)
+    # and the values are the percentage to limit by.
+    processes_to_limit = {
+        "chrome.exe": 90,       # Limit Chrome to 10% CPU (90% limit)
+        "spotify.exe": 95,      # Limit Spotify to 5% CPU (95% limit)
+        "YouTube": 85           # Limit any window with "YouTube" in the title to 15% CPU
+    }
+
+    print("📝 Initializing and starting limiter for:")
+    for proc, limit in processes_to_limit.items():
+        print(f"   ✅ {proc} (limited by {limit}%)")
+
+    # Initialize the limiter and it will automatically start limiting the processes.
+    limiter = CpuLimiter(processes_to_limit)
+
+    print("\n🔄 CPU limiting is now active...")
     print("💡 Check Task Manager to see the effect!")
     print("⌨️  Press Ctrl+C to stop\n")
-    
-    # Start limiting all added processes
-    limiter.start_all()
-    
+
     try:
         # Let it run and show status every 10 seconds
-        for i in range(6):  # Run for 60 seconds total
+        while True:
             time.sleep(10)
             active_limits = limiter.get_active()
-            print(f"📊 Status update #{i+1}: {len(active_limits)} processes being limited")
-            
-            if not active_limits:
-                print("💡 No processes found to limit. Make sure the target applications are running.")
-    
+            if active_limits:
+                print(f"📊 Status: {len(active_limits)} processes are being actively limited.")
+            else:
+                print("💡 No target processes found. Make sure they are running.")
+                break
+
     except KeyboardInterrupt:
-        print("\n⚠️  Stopping early due to user interrupt...")
-    
+        print("\n⚠️  Stopping due to user interrupt...")
+
     finally:
         print("🛑 Stopping all CPU limits...")
-        limiter.stop_all()
+        limiter.shutdown() # shutdown() is an alias for stop_all()
         print("✅ All limits removed. Applications restored to normal speed.")
 
+
 if __name__ == "__main__":
     import ctypes
     import sys
-    
-    # Check for admin privileges
-    try:
-        is_admin = ctypes.windll.shell32.IsUserAnAdmin()
-    except:
-        is_admin = False
-    
-    if not is_admin:
-        print("🔐 This script requires Administrator privileges")
-        print("🔄 Please run as Administrator and try again")
-        input("Press Enter to exit...")
-        sys.exit(1)
-    
-    main()
+    # check if the script is run with Administrator 
+    if ctypes.windll.shell32.IsUserAnAdmin():
+        main()
+    else:
+        print("⚠️  This script requires Administrator privileges.")
+        choice = input("Do you want to restart with admin rights? (y/n): ").strip().lower()
+        if choice == 'y':
+            print("🔄 Attempting to re-launch with elevation...")
+            ctypes.windll.shell32.ShellExecuteW(None, "runas", sys.executable, " ".join(sys.argv), None, 1)
+        else:
+            print("❌ Exiting. Please run as Administrator manually.")
diff --git a/setup.py b/setup.py
diff --git a/simple_limit.py b/simple_limit.py
