Configuration Management

class PyngrokConfig:
    """
    Configuration object for pyngrok's interaction with the ngrok binary.
    """
    def __init__(self,
                 ngrok_path=None,
                 config_path=None,
                 auth_token=None,
                 region=None,
                 monitor_thread=True,
                 log_event_callback=None,
                 startup_timeout=15,
                 max_logs=100,
                 request_timeout=4.0,
                 start_new_session=False,
                 ngrok_version="v3",
                 api_key=None,
                 config_version="2"):
        """
        Create a pyngrok configuration object.

        Parameters:
        - ngrok_path (str, optional): Path to ngrok binary
        - config_path (str, optional): Path to ngrok config file
        - auth_token (str, optional): ngrok auth token (overrides NGROK_AUTHTOKEN env var)
        - region (str, optional): ngrok region (us, eu, ap, au, sa, jp, in)
        - monitor_thread (bool): Whether to monitor ngrok after startup
        - log_event_callback (callable, optional): Callback for log events
        - startup_timeout (int): Max seconds to wait for ngrok startup
        - max_logs (int): Max number of logs to store in process
        - request_timeout (float): Timeout for ngrok API requests
        - start_new_session (bool): Start ngrok in new session (POSIX only)
        - ngrok_version (str): Major ngrok version ("v2" or "v3")
        - api_key (str, optional): ngrok API key (overrides NGROK_API_KEY env var)
        - config_version (str): ngrok config version
        """

    # Properties available after initialization
    ngrok_path: str
    config_path: str
    auth_token: str
    region: str
    monitor_thread: bool
    log_event_callback: callable
    startup_timeout: int
    max_logs: int
    request_timeout: float
    start_new_session: bool
    ngrok_version: str
    api_key: str
    config_version: str

from pyngrok import conf

# Create basic configuration
pyngrok_config = conf.PyngrokConfig(
    auth_token="your_auth_token_here",
    region="us"
)

# Create advanced configuration
advanced_config = conf.PyngrokConfig(
    ngrok_path="/usr/local/bin/ngrok",
    config_path="/custom/path/ngrok.yml",
    auth_token="your_token",
    region="eu",
    startup_timeout=30,
    request_timeout=10.0,
    ngrok_version="v3",
    api_key="your_api_key"
)

# Configuration with logging callback
def log_callback(log):
    print(f"ngrok: {log.msg}")

logging_config = conf.PyngrokConfig(
    log_event_callback=log_callback,
    monitor_thread=True
)

def get_default():
    """
    Get the current default configuration.

    Returns:
    PyngrokConfig: The default pyngrok configuration
    """

def set_default(pyngrok_config):
    """
    Set a new default configuration.

    Parameters:
    - pyngrok_config (PyngrokConfig): The new default configuration
    """

from pyngrok import conf, ngrok

# Get current default config
default_config = conf.get_default()
print(f"Default ngrok path: {default_config.ngrok_path}")

# Update default config
new_config = conf.PyngrokConfig(
    auth_token="your_token",
    region="eu"
)
conf.set_default(new_config)

# All subsequent operations use the new defaults
tunnel = ngrok.connect("8000")  # Uses auth_token and eu region

# Or update just one property of the default
conf.get_default().auth_token = "new_token"

def get_config_path(pyngrok_config):
    """
    Get the config file path from pyngrok_config or return ngrok's default.

    Parameters:
    - pyngrok_config (PyngrokConfig): Configuration to check for config_path

    Returns:
    str: Path to the ngrok config file
    """

from pyngrok import conf

# Get config path for a configuration
pyngrok_config = conf.PyngrokConfig(config_path="/custom/ngrok.yml")
config_path = conf.get_config_path(pyngrok_config)
print(f"Config path: {config_path}")

# Get default config path
default_config = conf.get_default()
default_path = conf.get_config_path(default_config)
print(f"Default config path: {default_path}")

from pyngrok import conf, ngrok

# Configuration with auth token for multiple tunnels
auth_config = conf.PyngrokConfig(
    auth_token="your_ngrok_authtoken_here"
)

# Use with tunnel creation
tunnel1 = ngrok.connect("8000", pyngrok_config=auth_config)
tunnel2 = ngrok.connect("9000", pyngrok_config=auth_config)

# Configuration with API key for advanced features
api_config = conf.PyngrokConfig(
    auth_token="your_authtoken",
    api_key="your_api_key"
)

# Set as default for all operations
conf.set_default(api_config)

# Now all operations have access to API features
agent_status = ngrok.get_agent_status()

# Set environment variables
export NGROK_AUTHTOKEN="your_authtoken_here"
export NGROK_API_KEY="your_api_key_here"

from pyngrok import conf, ngrok

# Configuration automatically picks up environment variables
config = conf.PyngrokConfig()
print(f"Auth token from env: {config.auth_token}")
print(f"API key from env: {config.api_key}")

# Override environment variables if needed
override_config = conf.PyngrokConfig(
    auth_token="different_token"  # Overrides NGROK_AUTHTOKEN
)

from pyngrok import conf, ngrok

# Configure for different regions
us_config = conf.PyngrokConfig(region="us")
eu_config = conf.PyngrokConfig(region="eu")
ap_config = conf.PyngrokConfig(region="ap")

# Use region-specific config
us_tunnel = ngrok.connect("8000", pyngrok_config=us_config)
eu_tunnel = ngrok.connect("9000", pyngrok_config=eu_config)

print(f"US tunnel: {us_tunnel.public_url}")
print(f"EU tunnel: {eu_tunnel.public_url}")

from pyngrok import conf, ngrok
import logging

# Set up logging
logging.basicConfig(level=logging.INFO)

def custom_log_handler(log):
    if log.lvl == "ERROR":
        logging.error(f"ngrok error: {log.msg}")
    else:
        logging.info(f"ngrok: {log.msg}")

# Advanced process configuration
process_config = conf.PyngrokConfig(
    monitor_thread=True,
    log_event_callback=custom_log_handler,
    startup_timeout=30,
    max_logs=200,
    request_timeout=10.0,
    start_new_session=True  # POSIX only
)

# Use with tunnel operations
ngrok.connect("8000", pyngrok_config=process_config)

from pyngrok import conf

# Configuration for ngrok v2
v2_config = conf.PyngrokConfig(
    ngrok_version="v2",
    config_version="2"
)

# Configuration for ngrok v3 (default)
v3_config = conf.PyngrokConfig(
    ngrok_version="v3",
    config_version="2"
)

# The ngrok_version affects available features and command syntax

# Available constants in pyngrok.conf
DEFAULT_CONFIG_PATH: str  # Default config path (None uses ngrok default)
DEFAULT_NGROK_DIR: str    # Default ngrok directory
DEFAULT_NGROK_CONFIG_PATH: str  # Default ngrok config file path
DEFAULT_NGROK_PATH: str   # Default ngrok binary path

from pyngrok import conf

print(f"Default ngrok directory: {conf.DEFAULT_NGROK_DIR}")
print(f"Default ngrok path: {conf.DEFAULT_NGROK_PATH}")
print(f"Default config path: {conf.DEFAULT_NGROK_CONFIG_PATH}")