FortScript

https://github.com/wesleyqdev/fortscript
Admin
FortScript automatically pauses and resumes your scripts, bots, and applications when you start...
Tokens:7,644
Snippets:55
Trust Score:5.8
License:MIT
Update:9 months ago
Show doc for...
Tokens:
Raw
### Basic FortScript Setup (Python)

Source: https://github.com/wesleyqdev/fortscript/blob/main/README.md

Demonstrates the most basic FortScript setup by loading settings from a default `fortscript.yaml` file and running the application. This is suitable for simple configurations.

```python
from fortscript import FortScript

# Loads settings from fortscript.yaml
app = FortScript()
app.run()
```

--------------------------------

### FortScript YAML Configuration Example

Source: https://context7.com/wesleyqdev/fortscript/llms.txt

An example YAML file demonstrating how to configure FortScript, including projects to manage, heavy processes that trigger script pausing, and RAM thresholds. This file can be referenced directly by the FortScript class.

```yaml
# Projects managed by FortScript
projects:
  - name: "My Discord Bot"
    path: "./bot/main.py"

  - name: "Node API"
    path: "./api/package.json"

  - name: "Local Server"
    path: "./server/app.exe"

# Applications that pause scripts
heavy_processes:
  - name: "GTA V"
    process: "gta5"

  - name: "OBS Studio"
    process: "obs64"

  - name: "Premiere Pro"
    process: "premiere"

# RAM configuration
ram_threshold: 90
ram_safe: 80
log_level: "INFO"
```

--------------------------------

### Python FortScript Integration Example

Source: https://context7.com/wesleyqdev/fortscript/llms.txt

This comprehensive Python example shows how to integrate FortScript into a development environment. It configures logging, defines projects, specifies heavy processes (including games), sets RAM thresholds with hysteresis, and defines custom callback functions for pause and resume events. The script initializes and runs the FortScript application.

```python
import os
import logging
from fortscript import FortScript, GAMES, RamConfig, Callbacks

# Configure logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s'
)

# Project structure
base_dir = os.path.dirname(os.path.abspath(__file__))
projects = [
    {
        "name": "Discord Bot",
        "path": os.path.join(base_dir, "bots", "discord_bot.py")
    },
    {
        "name": "API Server",
        "path": os.path.join(base_dir, "api", "package.json")
    },
    {
        "name": "Database Sync",
        "path": os.path.join(base_dir, "sync", "db_sync.py")
    },
]

# Use built-in games list + custom processes
heavy_processes = GAMES + [
    {"name": "Docker Desktop", "process": "docker"},
    {"name": "Android Studio", "process": "studio64"},
]

# RAM configuration with 10% hysteresis gap
ram_config = RamConfig(threshold=90, safe=80)

# Event handlers with detailed logging
def on_pause_handler():
    logging.warning("=" * 60)
    logging.warning("🎮 PAUSE EVENT: Gaming/Heavy app detected")
    logging.warning("All development scripts have been stopped")
    logging.warning("=" * 60)

def on_resume_handler():
    logging.info("=" * 60)
    logging.info("💻 RESUME EVENT: System resources available")
    logging.info("Restarting development environment...")
    logging.info("=" * 60)

callbacks = Callbacks(
    on_pause=on_pause_handler,
    on_resume=on_resume_handler
)

# Initialize FortScript
app = FortScript(
    projects=projects,
    heavy_process=heavy_processes,
    ram_config=ram_config,
    callbacks=callbacks,
    log_level="INFO",
    new_console=False  # Keep in same console for logging
)

if __name__ == "__main__":
    logging.info("🚀 Starting FortScript Development Manager")
    logging.info(f"📁 Projects: {len(projects)}")
    logging.info(f"🎯 Monitored processes: {len(heavy_processes)}")
    logging.info(f"💾 RAM threshold: {ram_config.threshold}%")
    logging.info(f"💾 RAM safe: {ram_config.safe}%")

    try:
        app.run()
    except KeyboardInterrupt:
        logging.info("\n⏹️ FortScript stopped by user")
    except Exception as e:
        logging.error(f"❌ Fatal error: {e}")
        raise

```

--------------------------------

### Global FortScript CLI Installation (Bash)

Source: https://github.com/wesleyqdev/fortscript/blob/main/README.md

Install FortScript globally using pipx to enable the `fort` command directly in your terminal. This allows you to manage scripts without writing Python code.

```bash
pipx install fortscript
```

--------------------------------

### FortScript Gaming Mode Example (Python)

Source: https://github.com/wesleyqdev/fortscript/blob/main/README.md

A practical example demonstrating FortScript's gaming mode, where work scripts are paused during gaming sessions. It utilizes the built-in `GAMES` list and custom callbacks for a seamless experience.

```python
import os
from fortscript import FortScript, GAMES, RamConfig, Callbacks

# Project paths
base_dir = os.path.dirname(os.path.abspath(__file__))
bot_path = os.path.join(base_dir, "discord_bot", "main.py")
api_path = os.path.join(base_dir, "local_api", "package.json")

# Projects to manage
projects = [
    {"name": "Discord Bot", "path": bot_path},
    {"name": "Local API", "path": api_path},
]

# Combining the default game list with custom processes
# GAMES already includes GTA, Valorant, CS2, LOL, Fortnite, etc.
heavy_processes = GAMES + [
    {"name": "Video Editor", "process": "premiere"},
    {"name": "C++ Compiler", "process": "cl"}
]

def on_pause():
    print("=" * 50)
    print("🎮 GAMING MODE ACTIVE! Scripts paused to free up resources.")
    print("=" * 50)

def on_resume():
    print("=" * 50)
    print("💻 WORK MODE - Resuming your scripts...")
    print("=" * 50)

# Configuration
ram_config = RamConfig(threshold=85, safe=75)

callbacks = Callbacks(
    on_pause=on_pause,
    on_resume=on_resume,
)

# Initialize FortScript
app = FortScript(
    projects=projects,
    heavy_process=heavy_processes,
    ram_config=ram_config,
    callbacks=callbacks,
)

if __name__ == "__main__":
    print("🎯 FortScript: Gaming Mode Started")
    app.run()
```

--------------------------------

### FortScript CLI Usage (Bash)

Source: https://github.com/wesleyqdev/fortscript/blob/main/README.md

Provides instructions for using the FortScript Command Line Interface (CLI) for quick setup or basic testing. Note that local customization via CLI is currently limited.

```bash
fort
```

--------------------------------

### CLI Command Usage (Bash)

Source: https://context7.com/wesleyqdev/fortscript/llms.txt

Demonstrates how to install and run Fortscript from the terminal. The `fort` command loads global configurations from the package's internal `fortscript.yaml`. For custom configurations, it's recommended to use Python scripts.

```bash
# Install globally with pipx
pipx install fortscript

# Run the CLI
fort

# The CLI loads configuration from the package's internal fortscript.yaml
# For custom configurations, use Python scripts instead
```

--------------------------------

### FortScript Python Configuration and Execution

Source: https://github.com/wesleyqdev/fortscript/blob/main/README.md

Configure and run FortScript programmatically using Python. This allows for dynamic configuration of projects, heavy processes, RAM settings, and log levels directly within your script. The `run()` method starts the FortScript application.

```python
from fortscript import FortScript, RamConfig

projects = [
    {"name": "My Bot", "path": "./bot/main.py"},
    {"name": "Node API", "path": "./api/package.json"},
]

heavy_processes = [
    {"name": "GTA V", "process": "gta5"},
    {"name": "OBS Studio", "process": "obs64"},
]

ram_config = RamConfig(threshold=90, safe=80)

app = FortScript(
    projects=projects,
    heavy_process=heavy_processes,
    ram_config=ram_config,
    log_level="INFO",
)

app.run()
```

--------------------------------

### Install FortScript as a Project Dependency (Bash)

Source: https://github.com/wesleyqdev/fortscript/blob/main/README.md

Install FortScript as a dependency for your Python project using various package managers like UV, Poetry, or pip. This makes FortScript's functionality available within your project's environment.

```bash
# UV (recommended)
uv add fortscript

# Poetry
poetry add fortscript

# pip
pip install fortscript
```

--------------------------------

### Complete FortScript Configuration with Dynamic Python (Python)

Source: https://github.com/wesleyqdev/fortscript/blob/main/README.md

Illustrates a comprehensive FortScript configuration using Python, allowing dynamic definition of projects, heavy processes, RAM configurations, and callbacks. This provides maximum flexibility for organizing code.

```python
from fortscript import FortScript, RamConfig, Callbacks

# 1. Define your callbacks
def notify_pause():
    print("⏸️ Scripts paused!")

def notify_resume():
    print("▶️ Scripts resumed!")

# 2. Define your projects
my_projects = [
    {"name": "Discord Bot", "path": "./bot/main.py"},
    {"name": "Express API", "path": "./api/package.json"},
    {"name": "Server", "path": "./server/app.exe"},
]

# 3. Define heavy processes
my_processes = [
    {"name": "GTA V", "process": "gta5"},
    {"name": "Cyberpunk 2077", "process": "cyberpunk2077"},
    {"name": "Chrome (Heavy)", "process": "chrome"},
]

# 4. Initialize FortScript
app = FortScript(
    projects=my_projects,
    heavy_process=my_processes,
    ram_config=RamConfig(threshold=90, safe=80),
    callbacks=Callbacks(
        on_pause=notify_pause,
        on_resume=notify_resume
    ),
    log_level="DEBUG",
)

app.run()
```

--------------------------------

### Initialize FortScript with Projects, Processes, and Callbacks in Python

Source: https://context7.com/wesleyqdev/fortscript/llms.txt

Initialize the FortScript class programmatically in Python, defining projects to manage, heavy processes that trigger pausing, RAM thresholds, and custom callback functions for pause/resume events. This method is suitable for direct integration into Python applications.

```python
from fortscript import FortScript, RamConfig, Callbacks

# Define projects to manage
projects = [
    {"name": "Discord Bot", "path": "./bot/main.py"},
    {"name": "Express API", "path": "./api/package.json"},
    {"name": "Local Server", "path": "./server/app.exe"},
]

# Define heavy processes that trigger pausing
heavy_processes = [
    {"name": "GTA V", "process": "gta5"},
    {"name": "Cyberpunk 2077", "process": "cyberpunk2077"},
    {"name": "OBS Studio", "process": "obs64"},
]

# Configure RAM thresholds
ram_config = RamConfig(threshold=90, safe=80)

# Define callback functions
def on_pause():
    print("🎮 Gaming mode active! Scripts paused.")

def on_resume():
    print("💻 Back to work! Scripts resumed.")

callbacks = Callbacks(on_pause=on_pause, on_resume=on_resume)

# Initialize FortScript
app = FortScript(
    projects=projects,
    heavy_process=heavy_processes,
    ram_config=ram_config,
    callbacks=callbacks,
    log_level="INFO",
    new_console=True  # Windows: launch scripts in separate console
)

# Start monitoring and management
app.run()
```

--------------------------------

### Load FortScript Configuration from YAML in Python

Source: https://context7.com/wesleyqdev/fortscript/llms.txt

Load FortScript configuration from an external YAML file, enabling cleaner project organization and easier management of settings. Custom event handlers can still be provided via Python callbacks.

```python
from fortscript import FortScript, Callbacks
import logging

logging.basicConfig(level=logging.INFO, format='%(message)s')

# Custom event handlers
def alert_pause():
    print("📢 Resource threshold reached! Pausing overlays.")

def alert_resume():
    print("✅ Resources cleared. Overlays live again!")

callbacks = Callbacks(on_pause=alert_pause, on_resume=alert_resume)

# Load from YAML file (fortscript.yaml)
app = FortScript(
    config_path="fortscript.yaml",
    callbacks=callbacks
)

app.run()
```

--------------------------------

### Python Equivalent of CLI Usage (Python)

Source: https://context7.com/wesleyqdev/fortscript/llms.txt

Shows the Python code that mimics the functionality of the Fortscript CLI. It configures Rich logging for better output and loads configuration from a `fortscript.yaml` file, allowing for programmatic control similar to the command-line interface.

```python
import logging
import os
from rich.console import Console
from rich.logging import RichHandler
from fortscript import FortScript

# Configure Rich logging
logging.basicConfig(
    level='INFO',
    format='%(message)s',
    datefmt='[%X]',
    handlers=[RichHandler(rich_tracebacks=True, show_path=False)],
)

console = Console()
console.print("[bold color(220)]FORT[/][bold color(87)]SCRIPT[/] [dim]v0.4.0")

# Load configuration
config_path = os.path.join(
    os.path.dirname(os.path.abspath(__file__)), 'fortscript.yaml'
)

app = FortScript(config_path=config_path)
app.run()
```

--------------------------------

### FortScript with Event Callbacks (Python)

Source: https://github.com/wesleyqdev/fortscript/blob/main/README.md

Shows how to integrate custom functions to be executed when scripts are paused or resumed. This allows for user-defined actions during state changes.

```python
from fortscript import FortScript, Callbacks

def when_paused():
    print("🎮 Gaming mode active! Scripts paused.")

def when_resumed():
    print("💻 Back to work! Scripts resumed.")

callbacks = Callbacks(
    on_pause=when_paused,
    on_resume=when_resumed,
)

app = FortScript(
    config_path="fortscript.yaml",
    callbacks=callbacks,
)

app.run()
```

--------------------------------

### Monitor System RAM Usage (Python)

Source: https://context7.com/wesleyqdev/fortscript/llms.txt

Provides functionality to track system RAM usage percentage. The `RamMonitoring` class allows retrieving the current memory utilization, which can be used for resource-based script management or to inform decisions about pausing or resuming tasks.

```python
from fortscript.main import RamMonitoring
import time

# Initialize RAM monitoring
ram_monitor = RamMonitoring()

# Get current RAM usage
current_usage = ram_monitor.get_percent()
print(f"Current RAM usage: {current_usage}%")
```

--------------------------------

### Monitor Specific Applications (Python)

Source: https://context7.com/wesleyqdev/fortscript/llms.txt

Implements application monitoring to detect running processes. The `AppsMonitoring` class takes a list of `HeavyProcessConfig` objects, each specifying an application name and its process executable name. It provides a method to check which of these applications are currently active in the system.

```python
from fortscript.main import AppsMonitoring, HeavyProcessConfig
from typing import List

# Define processes to monitor
heavy_processes: List[HeavyProcessConfig] = [
    {"name": "Chrome", "process": "chrome"},
    {"name": "GTA V", "process": "gta5"},
    {"name": "Visual Studio", "process": "devenv"},
]

# Initialize monitoring
monitor = AppsMonitoring(heavy_processes)

# Check which processes are currently active
status = monitor.active_process_list()
print("Process Status:")
for app_name, is_running in status.items():
    status_icon = "✅" if is_running else "❌"
    print(f"{status_icon} {app_name}: {'Running' if is_running else 'Not Running'}")

# Example output:
# Process Status:
# ❌ Chrome: Not Running
# ✅ GTA V: Running
# ❌ Visual Studio: Not Running

# Use in monitoring loop
if any(status.values()):
    print("Heavy process detected - pausing scripts")
else:
    print("No heavy processes - resuming scripts")
```

--------------------------------

### FortScript YAML Configuration

Source: https://github.com/wesleyqdev/fortscript/blob/main/README.md

Configure FortScript using a YAML file (`fortscript.yaml`) in your project root. This includes defining managed projects, heavy processes to monitor, and RAM thresholds for pausing/resuming scripts. It also allows setting the log level.

```yaml
# ====================================
# FORTSCRIPT CONFIGURATION
# ====================================

# Scripts/projects that FortScript will manage
# FortScript starts these processes automatically
projects:
  - name: "My Discord Bot" # Friendly name (appears in logs)
    path: "./bot/main.py" # Python script (.py)

  - name: "Node API"
    path: "./api/package.json" # Node.js project (package.json)

  - name: "Local Server"
    path: "./server/app.exe" # Windows executable (.exe)

# Applications that will pause the scripts above
# When any of these processes are detected, scripts stop
heavy_processes:
  - name: "GTA V" # Friendly name
    process: "gta5" # Process name (without .exe)

  - name: "OBS Studio"
    process: "obs64"

  - name: "Cyberpunk 2077"
    process: "cyberpunk2077"

  - name: "Premiere Pro"
    process: "premiere"

# RAM threshold to pause scripts (%)
# If system RAM exceeds this value, scripts are paused
ram_threshold: 90

# Safe RAM limit to resume scripts (%)
# Scripts only return when RAM falls below this value
# This avoids constant toggling (hysteresis)
ram_safe: 80

# Log level (DEBUG, INFO, WARNING, ERROR)
# Use DEBUG to see detailed information during development
log_level: "INFO"
```

--------------------------------

### Integrate FortScript with Built-in GAMES List in Python

Source: https://context7.com/wesleyqdev/fortscript/llms.txt

Utilize FortScript's pre-defined list of popular games and heavy applications by merging it with custom processes. This simplifies configuration when managing scripts alongside common gaming applications.

```python
import os
from fortscript import FortScript, GAMES, RamConfig, Callbacks

# Project paths
base_dir = os.path.dirname(os.path.abspath(__file__))
bot_path = os.path.join(base_dir, "discord_bot", "main.py")
api_path = os.path.join(base_dir, "local_api", "package.json")

# Projects to manage
projects = [
    {"name": "Discord Bot", "path": bot_path},
    {"name": "Local API", "path": api_path},
]

# Combine built-in GAMES list with custom processes
heavy_processes = GAMES + [
    {"name": "Video Editor", "process": "premiere"},
    {"name": "C++ Compiler", "process": "cl"}
]

def on_pause():
    print("=" * 50)
    print("🎮 GAMING MODE ACTIVE! Scripts paused.")
    print("=" * 50)

def on_resume():
    print("=" * 50)
    print("💻 WORK MODE - Resuming scripts...")
    print("=" * 50)

ram_config = RamConfig(threshold=85, safe=75)
callbacks = Callbacks(on_pause=on_pause, on_resume=on_resume)

app = FortScript(
    projects=projects,
    heavy_process=heavy_processes,
    ram_config=ram_config,
    callbacks=callbacks,
)

if __name__ == "__main__":
    print("🎯 FortScript: Gaming Mode Started")
    print(f"Monitoring {len(GAMES)} games automatically")
    app.run()
```

--------------------------------

### Python RAM Monitoring Loop with Threshold Checking

Source: https://context7.com/wesleyqdev/fortscript/llms.txt

This Python snippet demonstrates a continuous loop that monitors RAM usage. It checks if the RAM usage exceeds a defined threshold or falls below a safe level, printing messages and suggesting actions. It utilizes a 'ram_monitor' object and 'time.sleep' for periodic checks.

```python
threshold = 85.0
safe_level = 75.0

while True:
    ram_usage = ram_monitor.get_percent()

    if ram_usage > threshold:
        print(f"⚠️ HIGH RAM: {ram_usage}% (Threshold: {threshold}%)")
        print("Action: Pausing scripts...")
        # Trigger pause action
    elif ram_usage < safe_level:
        print(f"✅ SAFE RAM: {ram_usage}% (Safe level: {safe_level}%)")
        print("Action: Scripts can resume...")
        # Trigger resume action
    else:
        print(f"📊 RAM: {ram_usage}% (Hysteresis zone)")

    time.sleep(5)
```

--------------------------------

### Configure RAM Monitoring with Hysteresis (Python)

Source: https://context7.com/wesleyqdev/fortscript/llms.txt

Sets up RAM monitoring to prevent frequent script toggling. The `RamConfig` object defines a threshold for pausing scripts and a safe level for resuming them, with automatic adjustment if the safe level is too high relative to the threshold. It's used within the `FortScript` class to manage script execution based on system RAM.

```python
from fortscript import RamConfig, FortScript

# RAM configuration with hysteresis
ram_config = RamConfig(
    threshold=90,  # Pause scripts when RAM exceeds 90%
    safe=80        # Resume only when RAM drops below 80%
)

# Automatic adjustment: if safe >= threshold, safe is set to (threshold - 10)
invalid_config = RamConfig(threshold=85, safe=90)
print(f"Adjusted safe value: {invalid_config.safe}")  # Output: 75

projects = [{"name": "API", "path": "./api/main.py"}]
heavy_processes = [{"name": "Game", "process": "game"}]

app = FortScript(
    projects=projects,
    heavy_process=heavy_processes,
    ram_config=ram_config,
    log_level="DEBUG"
)

app.run()
```

--------------------------------

### Configure Callbacks for Pause/Resume Events (Python)

Source: https://context7.com/wesleyqdev/fortscript/llms.txt

Allows defining custom functions to be executed when scripts are paused or resumed. This is useful for integrating notifications (e.g., Discord webhooks), logging, or other external system interactions. The `Callbacks` object is passed to the `FortScript` constructor.

```python
from fortscript import FortScript, Callbacks
import requests
import logging

# Configure logging
logging.basicConfig(level=logging.INFO)

def notify_discord_pause():
    """Send Discord webhook when scripts pause"""
    webhook_url = "https://discord.com/api/webhooks/YOUR_WEBHOOK"
    try:
        requests.post(webhook_url, json={
            "content": "⏸️ Development scripts paused - Gaming mode active!"
        })
    except Exception as e:
        logging.error(f"Discord notification failed: {e}")

def notify_discord_resume():
    """Send Discord webhook when scripts resume"""
    webhook_url = "https://discord.com/api/webhooks/YOUR_WEBHOOK"
    try:
        requests.post(webhook_url, json={
            "content": "▶️ Scripts resumed - Back to development mode!"
        })
    except Exception as e:
        logging.error(f"Discord notification failed: {e}")

callbacks = Callbacks(
    on_pause=notify_discord_pause,
    on_resume=notify_discord_resume
)

projects = [{"name": "Bot", "path": "./bot.py"}]
heavy_processes = [{"name": "Game", "process": "valorant"}]

app = FortScript(
    config_path="fortscript.yaml",
    callbacks=callbacks
)

app.run()
```
Tokens:
Raw