#208 gdtest_stress_everything

---
title: Basic Example
---

# Basic Example

A basic example showing core functionality.

"""Package for the ultimate stress test combining everything."""

from .core import create_resource, ResourceManager
from .utils import format_output, validate_input

__all__ = [
    "create_resource",
    "ResourceManager",
    "format_output",
    "validate_input",
]

"""Core API: create_resource and ResourceManager."""


def create_resource(name: str, kind: str = "default") -> dict:
    """Create a new resource with the given name and kind.

    Initializes a resource and registers it in the internal
    registry. Uses :py:func:`validate_input` to check the
    name and :py:class:`ResourceManager` for lifecycle management.

    .. versionadded:: 2.0

    .. note:: This replaces the deprecated ``make_resource`` function.

    Parameters
    ----------
    name : str
        The name of the resource. Must be non-empty and contain
        only alphanumeric characters and hyphens.
    kind : str, optional
        The type of resource to create. One of ``"default"``,
        ``"premium"``, or ``"ephemeral"``. Defaults to ``"default"``.

    Returns
    -------
    dict
        A dictionary with the following keys:

        - ``"name"`` — the resource name (str).
        - ``"kind"`` — the resource kind (str).
        - ``"id"`` — the assigned resource ID (int).

    Raises
    ------
    ValueError
        If ``name`` is empty or ``kind`` is not recognized.

    Notes
    -----
    Resources created with ``kind="ephemeral"`` are automatically
    garbage-collected after 24 hours. The cleanup runs on a
    background timer managed by :py:class:`ResourceManager`.

    The resource ID is assigned sequentially using an atomic
    counter, so IDs are guaranteed to be unique within a
    single process.

    See Also
    --------
    ResourceManager : Manages resource lifecycle.
    validate_input : Validates resource names.

    Examples
    --------
    Create a default resource:

    >>> res = create_resource("my-item")
    >>> res["kind"]
    'default'

    Create a premium resource:

    >>> res = create_resource("premium-item", kind="premium")
    >>> res["name"]
    'premium-item'
    """
    if not name:
        raise ValueError("name must not be empty")
    if kind not in ("default", "premium", "ephemeral"):
        raise ValueError(f"Unknown kind: {kind}")
    return {"name": name, "kind": kind, "id": 1}


class ResourceManager:
    """Manages the lifecycle of resources.

    Provides methods for creating, reading, updating, deleting,
    listing, and reporting on resources.

    Parameters
    ----------
    namespace : str
        The namespace for this manager instance.

    Examples
    --------
    >>> mgr = ResourceManager("production")
    >>> mgr.list_resources()
    []
    """

    def __init__(self, namespace: str):
        """Initialize the ResourceManager.

        Parameters
        ----------
        namespace : str
            The namespace for this manager.
        """
        self.namespace = namespace
        self._resources: dict = {}
        self._counter = 0

    def add(self, name: str) -> dict:
        """Add a new resource.

        Parameters
        ----------
        name : str
            The name of the resource to add.

        Returns
        -------
        dict
            The added resource.

        Examples
        --------
        >>> mgr = ResourceManager("test")
        >>> mgr.add("item-1")
        {'name': 'item-1', 'id': 1}
        """
        self._counter += 1
        resource = {"name": name, "id": self._counter}
        self._resources[self._counter] = resource
        return resource

    def get(self, id: int) -> dict:
        """Get a resource by ID.

        Parameters
        ----------
        id : int
            The resource identifier.

        Returns
        -------
        dict
            The resource data.
        """
        return self._resources.get(id, {})

    def remove(self, id: int) -> bool:
        """Remove a resource by ID.

        Parameters
        ----------
        id : int
            The resource identifier to remove.

        Returns
        -------
        bool
            True if the resource was removed.
        """
        return self._resources.pop(id, None) is not None

    def list_resources(self) -> list:
        """List all managed resources.

        Returns
        -------
        list
            A list of all resource dictionaries.

        Examples
        --------
        >>> mgr = ResourceManager("test")
        >>> mgr.list_resources()
        []
        """
        return list(self._resources.values())

    def count(self) -> int:
        """Return the number of managed resources.

        Returns
        -------
        int
            The total count of resources.
        """
        return len(self._resources)

    def report(self) -> dict:
        """Generate a status report.

        Returns
        -------
        dict
            A report with namespace and resource count.

        Examples
        --------
        >>> mgr = ResourceManager("prod")
        >>> mgr.report()
        {'namespace': 'prod', 'count': 0}
        """
        return {"namespace": self.namespace, "count": len(self._resources)}

"""Utility functions: format_output and validate_input."""


def format_output(result: dict) -> str:
    """Format a result dictionary as a readable string.

    Parameters
    ----------
    result : dict
        The result dictionary to format.

    Returns
    -------
    str
        A formatted string representation.

    See Also
    --------
    validate_input : Validates input before processing.

    Examples
    --------
    >>> format_output({"name": "test", "id": 1})
    'name=test, id=1'
    """
    return ", ".join(f"{k}={v}" for k, v in result.items())


def validate_input(name: str) -> bool:
    """Validate a resource name.

    Parameters
    ----------
    name : str
        The resource name to validate.

    Returns
    -------
    bool
        True if the name is valid.

    Raises
    ------
    ValueError
        If the name is empty or contains invalid characters.

    Examples
    --------
    >>> validate_input("my-resource")
    True

    >>> validate_input("")
    Traceback (most recent call last):
        ...
    ValueError: name must not be empty
    """
    if not name:
        raise ValueError("name must not be empty")
    return True

---
title: Getting Started
---

# Getting Started

A step-by-step tutorial for new users.

---
title: Introduction
guide-section: Basics
---

# Introduction

Welcome to the Everything Stress Test package.

---
title: Installation
guide-section: Basics
---

# Installation

Install the package using pip.

---
title: Advanced Usage
guide-section: Advanced
---

# Advanced Usage

Advanced topics for power users.