"""Library-internal warning categories.

The closed-box redesign (v0.3+) collapses the v0.1 multi-call
bootstrap shape into a single :func:`mgf.common.bootstrap` call.
The v0.1 helpers (``setup_logging``, ``setup_otel``,
``install_excepthook``, ``install_threading_excepthook``) were
removed in the pre-v1.0 cleanup pass; ``mgf.common.bootstrap`` is
now the only supported entry point. Three additional names
(``configure``, ``make_settings_config``, ``EnvironmentError``)
were removed in v0.33.0 after completing their AP-12 cycle.

  - Consumer CI with ``filterwarnings = ["error"]`` (rule TS-04)
    sees the warning when running a v0.3+ install — the migration
    signal lands loudly.
  - Our OWN test suite (also ``filterwarnings = ["error"]``)
    selectively exempts the category via a per-class
    ``pyproject.toml`` filter so the v0.1-shape regression tests
    can keep passing without per-test marks.

The category is a subclass of :class:`DeprecationWarning` so
``python -W error::DeprecationWarning`` still escalates it,
matching the standard Python deprecation contract. Consumers that
want to ESCALATE our warnings to errors specifically can::

    import warnings
    from mgf.common._warnings import MgfDeprecationWarning
    warnings.filterwarnings("error", category=MgfDeprecationWarning)

This module has no other library code — keeping warning categories
in their own file means the public surface ``mgf.common._warnings``
is small and stable, and the import doesn't pull in anything
heavier (the warning classes are just empty subclasses).
"""

from __future__ import annotations


class MgfPlatformLimitation(UserWarning):
    """``UserWarning`` subclass for platform-specific limitations.

    Emitted when an API silently degrades on a platform that
    doesn't support the full feature set. Two examples:

      - ``run_command(process_group=True)`` on Windows: there's no
        ``os.killpg``, so the kill path falls back to per-PID
        ``terminate()``. Grandchildren (e.g., docker-compose
        children) are not cascade-killed. RA-09.

      - ``bootstrap()`` re-wiring OTel: OpenTelemetry's
        ``set_tracer_provider`` is one-shot per process. A second
        bootstrap with a different ``OtelSettings`` keeps the
        first bootstrap's provider. RA-16.

    Each emission site uses a module-level one-shot guard so the
    warning fires the FIRST time the limitation is hit, not every
    time. Consumers that want to silence per-platform warnings
    can::

        import warnings
        from mgf.common._warnings import MgfPlatformLimitation
        warnings.filterwarnings("ignore", category=MgfPlatformLimitation)

    Subclass of :class:`UserWarning` (not
    :class:`MgfDeprecationWarning`) because the limitation is a
    platform constraint, not a deprecation cycle — there's no
    plan to remove the API; the warning is permanent for that
    platform.
    """


class MgfDeprecationWarning(DeprecationWarning):
    """``DeprecationWarning`` subclass for ``mgf-common``'s own deprecations.

    Used by any current deprecation cycle that ``mgf-common`` runs
    on its public surface. Historical users (``configure``,
    ``make_settings_config``, ``EnvironmentError`` — completed in
    v0.33.0; the v0.1 observability shims ``setup_logging`` /
    ``setup_otel`` / ``install_excepthook`` /
    ``install_threading_excepthook`` — removed in the pre-v1.0
    cleanup) are kept on the codemod path in ``mgf-common migrate``.

    Allows consumer test suites + our own test suite to filter our
    deprecations selectively while keeping
    ``filterwarnings = ["error"]`` strict for everything else.

    Inherits from :class:`DeprecationWarning` so the standard
    ``-W error::DeprecationWarning`` flag still escalates it —
    we're not opting out of Python's deprecation contract, only
    adding a finer-grained handle.
    """


__all__ = ["MgfDeprecationWarning", "MgfPlatformLimitation"]
