Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/iFamishedX/HungerLib/llms.txt

Use this file to discover all available pages before exploring further.

HungerLib includes a small set of general-purpose utility functions that cover terminal housekeeping, pre-flight connectivity validation, and YAML-based configuration loading. clearTerminal and validateAll are importable directly from hungerlib; loadConfig is also exported from the top-level package. 
from hungerlib import clearTerminal, validateAll, loadConfig

​
clearTerminal

Clears the terminal screen using the appropriate system command for the current platform. Calls clear on POSIX systems (Linux, macOS) and cls on Windows. Useful at the start of a script loop to keep output readable. 
clearTerminal()
This function takes no parameters and returns None. 
from hungerlib import clearTerminal

clearTerminal()
print("=== HungerLib Automation Dashboard ===")

​
validateAll

Performs a three-step connectivity and state check against both the Pterodactyl panel and a specific server. Returns True only when all three checks pass, making it a reliable guard before running any automation that depends on the panel API and a live server. The three checks performed internally are:
  1. panel.ping() — verifies that the panel URL is reachable over HTTP.
  2. panel.validateAPI() — verifies that the API token is valid and accepted by the panel.
  3. server.getStatus() == 'running' — verifies that the target server is in the running power state.
validateAll(panel, server) -> bool
​
panel
Panel
required
An authenticated Panel instance to check for reachability and API validity.
​
server
Server
required
A GenericServer or MinecraftServer instance whose power state is checked.
Returns: bool — True if the panel is reachable, the API key is valid, and the server status is "running". Returns False if any check fails. 
from hungerlib import Panel, GenericServer, validateAll

panel = Panel("https://panel.example.com", "ptlc_yourtoken")
server = GenericServer(panel, "abc123", "My Server")

if not validateAll(panel, server):
    print("Pre-flight check failed — aborting.")
    exit(1)

print("All checks passed, proceeding with automation.")

​
loadConfig

Loads a typed configuration dataclass from a YAML file. This is HungerLib’s primary configuration system, designed to give automation scripts a structured, validated config with safe fallbacks and attribute-style YAML access. loadConfig reads from a user-editable YAML file, maps values to dataclass fields by dotted YAML path, applies fallback values when keys are absent, and attaches two special namespaces — .raw and .fallbacks — to the returned instance. 
loadConfig(schema, runtime_path=None)
​
schema
type
required
A dataclass class (not an instance) decorated with @dataclass that defines the configuration structure. The class must set __mode__ = "config" as a class-level attribute for loadConfig to treat field defaults as dotted YAML key paths.
​
runtime_path
str | None
default:"None"
Optional filesystem path to the YAML config file. If None, loadConfig reads __user_config_path__ from the schema class. If the file does not exist, the directory is created and either the default config (from __default_config_path__) is copied in, or an empty file is created.
Returns: An instance of schema populated with values from the YAML file (or fallbacks). Two additional attributes are attached at runtime:
​
config.raw
RawNamespace
A namespace object providing attribute-style access to the raw parsed YAML values. Attribute lookups resolve dotted YAML paths using the dataclass field defaults. Use this to read YAML values that were not mapped to a dataclass field, or to inspect the raw input before conversion.
​
config.fallbacks
object
The fallbacks class imported from the same module as schema. Contains the default values used when a YAML key is absent. Also used by Validator during schema validation.

​
Schema class attributes

Your dataclass schema can define the following class-level attributes to control loadConfig behaviour:
AttributeTypeDescription
__mode__strMust be "config" to enable dotted-path YAML resolution.
__user_config_path__strPath to the user’s editable YAML file (e.g. "config/config.yaml"). Used when runtime_path=None.
__default_config_path__strPackage-relative path to a bundled default YAML file. Copied to __user_config_path__ on first run if the user config does not yet exist.

​
Full example

# myapp/config.py
from dataclasses import dataclass

class fallbacks:
    host = "localhost"
    port = 25565
    debug = False

@dataclass
class Config:
    __mode__ = "config"
    __user_config_path__ = "config/config.yaml"
    __default_config_path__ = "defaults/config.yaml"

    host: str = "server.host"       # maps to YAML key "server.host"
    port: int = "server.port"       # maps to YAML key "server.port"
    debug: bool = "app.debug"       # maps to YAML key "app.debug"

# config/config.yaml
server:
  host: "play.example.com"
  port: 25566

app:
  debug: true

# main.py
from hungerlib import loadConfig
from myapp.config import Config

config = loadConfig(Config)

print(config.host)             # "play.example.com"
print(config.port)             # 25566
print(config.debug)            # True

# Raw YAML access
print(config.raw.host)         # "play.example.com" (via dotted path lookup)

# Fallback values
print(config.fallbacks.port)   # 25565
If a YAML key is missing, loadConfig falls back to the value defined in the fallbacks class in the same module as your schema. If no fallback is defined for a field, the value is set to None. Use HungerLib’s Validator system to enforce required fields and raise FatalError when critical keys are absent.

Build docs developers (and LLMs) love

Get started for freeTalk to us