Reference for ultralytics/utils/__init__.py

def __iter__(self):
    """Return self as iterator to satisfy Iterable interface."""
    return super().__iter__()

def to_csv(self, normalize=False, decimals=5):
    """
    Export results to CSV string format.

    Args:
       normalize (bool, optional): Normalize numeric values. Defaults to False.
       decimals (int, optional): Decimal precision. Defaults to 5.

    Returns:
       (str): CSV content as string.
    """
    return self.to_df(normalize=normalize, decimals=decimals).to_csv()

def to_df(self, normalize=False, decimals=5):
    """
    Create a pandas DataFrame from the prediction results summary or validation metrics.

    Args:
        normalize (bool, optional): Normalize numerical values for easier comparison. Defaults to False.
        decimals (int, optional): Decimal places to round floats. Defaults to 5.

    Returns:
        (DataFrame): DataFrame containing the summary data.
    """
    import pandas as pd  # scope for faster 'import ultralytics'

    return pd.DataFrame(self.summary(normalize=normalize, decimals=decimals))

def to_html(self, normalize=False, decimals=5, index=False):
    """
    Export results to HTML table format.

    Args:
        normalize (bool, optional): Normalize numeric values. Defaults to False.
        decimals (int, optional): Decimal precision. Defaults to 5.
        index (bool, optional): Whether to include index column in the HTML table. Defaults to False.

    Returns:
        (str): HTML representation of the results.
    """
    df = self.to_df(normalize=normalize, decimals=decimals)
    return "<table></table>" if df.empty else df.to_html(index=index)

def to_json(self, normalize=False, decimals=5):
    """
    Export results to JSON format.

    Args:
        normalize (bool, optional): Normalize numeric values. Defaults to False.
        decimals (int, optional): Decimal precision. Defaults to 5.

    Returns:
        (str): JSON-formatted string of the results.
    """
    return self.to_df(normalize=normalize, decimals=decimals).to_json(orient="records", indent=2)

def to_sql(self, normalize=False, decimals=5, table_name="results", db_path="results.db"):
    """
    Save results to an SQLite database.

    Args:
        normalize (bool, optional): Normalize numeric values. Defaults to False.
        decimals (int, optional): Decimal precision. Defaults to 5.
        table_name (str, optional): Name of the SQL table. Defaults to "results".
        db_path (str, optional): SQLite database file path. Defaults to "results.db".
    """
    df = self.to_df(normalize, decimals)
    if df.empty or df.columns.empty:  # Exit if df is None or has no columns (i.e., no schema)
        return

    import sqlite3

    conn = sqlite3.connect(db_path)
    cursor = conn.cursor()

    # Dynamically create table schema based on summary to support prediction and validation results export
    columns = []
    for col in df.columns:
        sample_val = df[col].dropna().iloc[0] if not df[col].dropna().empty else ""
        if isinstance(sample_val, dict):
            col_type = "TEXT"
        elif isinstance(sample_val, (float, int)):
            col_type = "REAL"
        else:
            col_type = "TEXT"
        columns.append(f'"{col}" {col_type}')  # Quote column names to handle special characters like hyphens

    # Create table (Drop table from db if it's already exist)
    cursor.execute(f'DROP TABLE IF EXISTS "{table_name}"')
    cursor.execute(f'CREATE TABLE "{table_name}" (id INTEGER PRIMARY KEY AUTOINCREMENT, {", ".join(columns)})')

    for _, row in df.iterrows():
        values = [json.dumps(v) if isinstance(v, dict) else v for v in row]
        column_names = ", ".join(f'"{col}"' for col in df.columns)
        placeholders = ", ".join("?" for _ in df.columns)
        cursor.execute(f'INSERT INTO "{table_name}" ({column_names}) VALUES ({placeholders})', values)

    conn.commit()
    conn.close()
    LOGGER.info(f"Results saved to SQL table '{table_name}' in '{db_path}'.")

def to_xml(self, normalize=False, decimals=5):
    """
    Export results to XML format.

    Args:
        normalize (bool, optional): Normalize numeric values. Defaults to False.
        decimals (int, optional): Decimal precision. Defaults to 5.

    Returns:
        (str): XML string.

    Note:
        Requires `lxml` package to be installed.
    """
    from ultralytics.utils.checks import check_requirements

    check_requirements("lxml")
    df = self.to_df(normalize=normalize, decimals=decimals)
    return '<?xml version="1.0" encoding="utf-8"?>\n<root></root>' if df.empty else df.to_xml()

def tojson(self, normalize=False, decimals=5):
    """Deprecated version of to_json()."""
    LOGGER.warning("'result.tojson()' is deprecated, replace with 'result.to_json()'.")
    return self.to_json(normalize, decimals)

def __getattr__(self, attr):
    """Custom attribute access error message with helpful information."""
    name = self.__class__.__name__
    raise AttributeError(f"'{name}' object has no attribute '{attr}'. See valid attributes below.\n{self.__doc__}")

def __repr__(self):
    """Return a machine-readable string representation of the object."""
    return self.__str__()

def __str__(self):
    """Return a human-readable string representation of the object."""
    attr = []
    for a in dir(self):
        v = getattr(self, a)
        if not callable(v) and not a.startswith("_"):
            if isinstance(v, SimpleClass):
                # Display only the module and class name for subclasses
                s = f"{a}: {v.__module__}.{v.__class__.__name__} object"
            else:
                s = f"{a}: {repr(v)}"
            attr.append(s)
    return f"{self.__module__}.{self.__class__.__name__} object with attributes:\n\n" + "\n".join(attr)

def __getattr__(self, attr):
    """Custom attribute access error message with helpful information."""
    name = self.__class__.__name__
    raise AttributeError(
        f"""
        '{name}' object has no attribute '{attr}'. This may be caused by a modified or out of date ultralytics
        'default.yaml' file.\nPlease update your code with 'pip install -U ultralytics' and if necessary replace
        {DEFAULT_CFG_PATH} with the latest version from
        https://github.com/ultralytics/ultralytics/blob/main/ultralytics/cfg/default.yaml
        """
    )

def __iter__(self):
    """Return an iterator of key-value pairs from the namespace's attributes."""
    return iter(vars(self).items())

def __str__(self):
    """Return a human-readable string representation of the object."""
    return "\n".join(f"{k}={v}" for k, v in vars(self).items())

def get(self, key, default=None):
    """Return the value of the specified key if it exists; otherwise, return the default value."""
    return getattr(self, key, default)

def __call__(self, f):
    """Run thread-safe execution of function or method."""
    from functools import wraps

    @wraps(f)
    def decorated(*args, **kwargs):
        """Applies thread-safety to the decorated function or method."""
        with self.lock:
            return f(*args, **kwargs)

    return decorated

@classmethod
def load(cls, file="data.yaml", append_filename=False):
    """
    Load YAML file to Python object with robust error handling.

    Args:
        file (str | Path): Path to YAML file.
        append_filename (bool): Whether to add filename to returned dict.

    Returns:
        (dict): Loaded YAML content.
    """
    instance = cls._get_instance()
    assert str(file).endswith((".yaml", ".yml")), f"Not a YAML file: {file}"

    # Read file content
    with open(file, errors="ignore", encoding="utf-8") as f:
        s = f.read()

    # Try loading YAML with fallback for problematic characters
    try:
        data = instance.yaml.load(s, Loader=instance.SafeLoader) or {}
    except Exception:
        # Remove problematic characters and retry
        s = re.sub(r"[^\x09\x0A\x0D\x20-\x7E\x85\xA0-\uD7FF\uE000-\uFFFD\U00010000-\U0010ffff]+", "", s)
        data = instance.yaml.load(s, Loader=instance.SafeLoader) or {}

    # Check for accidental user-error None strings (should be 'null' in YAML)
    if "None" in data.values():
        data = {k: None if v == "None" else v for k, v in data.items()}

    if append_filename:
        data["yaml_file"] = str(file)
    return data

@classmethod
def print(cls, yaml_file):
    """
    Pretty print YAML file or object to console.

    Args:
        yaml_file (str | Path | dict): Path to YAML file or dict to print.
    """
    instance = cls._get_instance()

    # Load file if path provided
    yaml_dict = cls.load(yaml_file) if isinstance(yaml_file, (str, Path)) else yaml_file

    # Use -1 for unlimited width in C implementation
    dump = instance.yaml.dump(yaml_dict, sort_keys=False, allow_unicode=True, width=-1, Dumper=instance.SafeDumper)

    LOGGER.info(f"Printing '{colorstr('bold', 'black', yaml_file)}'\n\n{dump}")

@classmethod
def save(cls, file="data.yaml", data=None, header=""):
    """
    Save Python object as YAML file.

    Args:
        file (str | Path): Path to save YAML file.
        data (dict | None): Dict or compatible object to save.
        header (str): Optional string to add at file beginning.
    """
    instance = cls._get_instance()
    if data is None:
        data = {}

    # Create parent directories if needed
    file = Path(file)
    file.parent.mkdir(parents=True, exist_ok=True)

    # Convert non-serializable objects to strings
    valid_types = int, float, str, bool, list, tuple, dict, type(None)
    for k, v in data.items():
        if not isinstance(v, valid_types):
            data[k] = str(v)

    # Write YAML file
    with open(file, "w", errors="ignore", encoding="utf-8") as f:
        if header:
            f.write(header)
        instance.yaml.dump(data, f, sort_keys=False, allow_unicode=True, Dumper=instance.SafeDumper)

def __enter__(self):
    """Executes when entering TryExcept context, initializes instance."""
    pass

def __exit__(self, exc_type, value, traceback):
    """Defines behavior when exiting a 'with' block, prints error message if necessary."""
    if self.verbose and value:
        LOGGER.warning(f"{self.msg}{': ' if self.msg else ''}{value}")
    return True

def __call__(self, func):
    """Decorator implementation for Retry with exponential backoff."""

    def wrapped_func(*args, **kwargs):
        """Applies retries to the decorated function or method."""
        self._attempts = 0
        while self._attempts < self.times:
            try:
                return func(*args, **kwargs)
            except Exception as e:
                self._attempts += 1
                LOGGER.warning(f"Retry {self._attempts}/{self.times} failed: {e}")
                if self._attempts >= self.times:
                    raise e
                time.sleep(self.delay * (2**self._attempts))  # exponential backoff delay

    return wrapped_func

def __delitem__(self, key):
    """Remove an item and update the persistent storage."""
    with self.lock:
        super().__delitem__(key)
        self._save()

def __setitem__(self, key, value):
    """Store a key-value pair and persist to disk."""
    with self.lock:
        super().__setitem__(key, value)
        self._save()

def __str__(self):
    """Return a pretty-printed JSON string representation of the dictionary."""
    contents = json.dumps(dict(self), indent=2, ensure_ascii=False, default=self._json_default)
    return f'JSONDict("{self.file_path}"):\n{contents}'

def clear(self):
    """Clear all entries and update the persistent storage."""
    with self.lock:
        super().clear()
        self._save()

def update(self, *args, **kwargs):
    """Update the dictionary and persist changes."""
    with self.lock:
        super().update(*args, **kwargs)
        self._save()

def __setitem__(self, key, value):
    """Updates one key: value pair."""
    self.update({key: value})

def reset(self):
    """Resets the settings to default and saves them."""
    self.clear()
    self.update(self.defaults)

def update(self, *args, **kwargs):
    """Updates settings, validating keys and types."""
    for arg in args:
        if isinstance(arg, dict):
            kwargs.update(arg)
    for k, v in kwargs.items():
        if k not in self.defaults:
            raise KeyError(f"No Ultralytics setting '{k}'. {self.help_msg}")
        t = type(self.defaults[k])
        if not isinstance(v, t):
            raise TypeError(
                f"Ultralytics setting '{k}' must be '{t.__name__}' type, not '{type(v).__name__}'. {self.help_msg}"
            )
    super().update(*args, **kwargs)