MNT: move enable_logging from utils.py into utilities.py

Removes the third helper module flagged in review. enable_logging is a
user-facing convenience, so it belongs in the public utilities module
alongside the other analysis helpers rather than in a standalone utils.py.

- rocketpy.utils.enable_logging -> rocketpy.utilities.enable_logging
- delete rocketpy/utils.py; expose rocketpy.utilities via __init__ (imported
  last, since utilities pulls in Environment/Rocket/encoders)
- move the logging unit tests into test_utilities.py; delete test_utils.py
- update the logging user guide and reference pages

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Gui-FernandesBR

docs/reference/classes/utils/logging.rst

@@ -1,5 +1,4 @@
 Logging functions
 -----------------
 
-.. automodule:: rocketpy.utils
-   :members:
+.. autofunction:: rocketpy.utilities.enable_logging

docs/reference/classes/utils/utilities.rst

@@ -11,4 +11,5 @@ At RocketPy projects, utilities are functions that:
 Below you have a list of all utilities functions available in rocketpy. 
 
 .. automodule:: rocketpy.utilities
-   :members:
+   :members:
+   :exclude-members: enable_logging

docs/user/logging.rst

@@ -18,14 +18,14 @@ Enabling logging
 -----------------
 
 The easiest way to see RocketPy's internal log messages is the
-:func:`rocketpy.utils.enable_logging` helper, which attaches a console
+:func:`rocketpy.utilities.enable_logging` helper, which attaches a console
 handler to RocketPy's logger hierarchy:
 
 .. jupyter-execute::
 
     import rocketpy
 
-    rocketpy.utils.enable_logging(level="INFO")
+    rocketpy.utilities.enable_logging(level="INFO")
 
 Once enabled, operations such as saving a file or completing a simulation
 will emit messages to the console, for example:
@@ -51,15 +51,15 @@ shown:
 .. jupyter-execute::
 
     # Show every internal runtime message, including solver ticks
-    rocketpy.utils.enable_logging(level="DEBUG")
+    rocketpy.utilities.enable_logging(level="DEBUG")
 
 Filtering by module
 --------------------
 
 Because each RocketPy module exposes its own logger (e.g.
 ``rocketpy.simulation.flight``, ``rocketpy.environment.environment``), you
 can rely on the standard ``logging`` module to filter or redirect messages
-from specific modules, without using :func:`rocketpy.utils.enable_logging`
+from specific modules, without using :func:`rocketpy.utilities.enable_logging`
 at all:
 
 .. code-block:: python

rocketpy/__init__.py

@@ -1,4 +1,3 @@
-from . import utils
 from .control import _Controller
 from .environment import Environment, EnvironmentAnalysis
 from .exceptions import (
@@ -70,3 +69,8 @@
     StochasticTail,
     StochasticTrapezoidalFins,
 )
+
+# Imported last: utilities pulls in Environment/Rocket/encoders, which are only
+# fully available once the imports above have run. Exposes
+# ``rocketpy.utilities`` (including ``enable_logging``) on ``import rocketpy``.
+from . import utilities

rocketpy/utilities.py

@@ -1,5 +1,6 @@
 import inspect
 import json
+import logging
 import os
 import warnings
 from datetime import date
@@ -22,6 +23,57 @@
     from .simulation.flight import Flight
 
 
+def enable_logging(level="WARNING"):
+    """Enable RocketPy logging output to the console.
+
+    Attaches a StreamHandler to the ``rocketpy`` logger so that internal
+    runtime events (simulation progress, warnings, errors) are printed to
+    the terminal. Only RocketPy logs are affected — global/root logging
+    is not modified. By default, only WARNING and above are shown.
+
+    Parameters
+    ----------
+    level : str, optional
+        The minimum logging level to display. Options are "DEBUG", "INFO",
+        "WARNING", "ERROR", and "CRITICAL". Default is "WARNING".
+
+    Examples
+    --------
+    Show only warnings and errors (default):
+
+    >>> import rocketpy
+    >>> rocketpy.utilities.enable_logging()
+
+    Show all internal runtime messages, including simulation progress:
+
+    >>> import rocketpy
+    >>> rocketpy.utilities.enable_logging(level="DEBUG")
+
+    Show confirmations like "Simulation completed" and "File saved":
+
+    >>> import rocketpy
+    >>> rocketpy.utilities.enable_logging(level="INFO")
+    """
+    numeric_level = getattr(logging, level.upper(), None)
+    if not isinstance(numeric_level, int):
+        raise ValueError(f"Invalid logging level: '{level}'")
+
+    logger = logging.getLogger("rocketpy")
+
+    # Remove any existing StreamHandlers to avoid duplicate messages
+    logger.handlers = [
+        h for h in logger.handlers if not isinstance(h, logging.StreamHandler)
+    ]
+
+    logger.setLevel(numeric_level)
+
+    handler = logging.StreamHandler()
+    handler.setLevel(numeric_level)
+    handler.setFormatter(logging.Formatter("%(levelname)s | %(name)s | %(message)s"))
+
+    logger.addHandler(handler)
+
+
 def compute_cd_s_from_drop_test(
     terminal_velocity, rocket_mass, air_density=1.225, g=9.80665
 ):

rocketpy/utils.py

@@ -1,3 +1,4 @@
+import logging
 import os
 from unittest.mock import patch
 
@@ -345,3 +346,79 @@ def test_load_from_rpy(mock_show):  # pylint: disable=unused-argument
     )
     assert loaded_flight.info() is None
     assert loaded_flight.all_info() is None
+
+
+# --- Logging (rocketpy.utilities.enable_logging) ------------------------------
+
+
+@pytest.fixture
+def reset_rocketpy_logger():
+    """Reset the rocketpy logger to its original state after each test."""
+    logger = logging.getLogger("rocketpy")
+    original_level = logger.level
+    original_handlers = logger.handlers[:]
+    yield
+    logger.handlers = original_handlers
+    logger.setLevel(original_level)
+
+
+def test_enable_logging_adds_stream_handler(reset_rocketpy_logger):
+    """enable_logging() must attach a StreamHandler to the rocketpy logger."""
+    utilities.enable_logging(level="INFO")
+
+    logger = logging.getLogger("rocketpy")
+    stream_handlers = [
+        h for h in logger.handlers if isinstance(h, logging.StreamHandler)
+    ]
+    assert len(stream_handlers) >= 1
+
+
+def test_enable_logging_sets_correct_level(reset_rocketpy_logger):
+    """enable_logging() must set the requested level on the rocketpy logger."""
+    utilities.enable_logging(level="DEBUG")
+    assert logging.getLogger("rocketpy").level == logging.DEBUG
+
+    utilities.enable_logging(level="WARNING")
+    assert logging.getLogger("rocketpy").level == logging.WARNING
+
+
+def test_enable_logging_no_duplicate_handlers(reset_rocketpy_logger):
+    """Calling enable_logging() twice must not duplicate StreamHandlers."""
+    utilities.enable_logging(level="INFO")
+    utilities.enable_logging(level="INFO")
+
+    logger = logging.getLogger("rocketpy")
+    stream_handlers = [
+        h for h in logger.handlers if isinstance(h, logging.StreamHandler)
+    ]
+    assert len(stream_handlers) == 1
+
+
+def test_enable_logging_replaces_handler_on_level_change(reset_rocketpy_logger):
+    """Calling enable_logging() with a new level must replace the old handler."""
+    utilities.enable_logging(level="WARNING")
+    utilities.enable_logging(level="DEBUG")
+
+    logger = logging.getLogger("rocketpy")
+    stream_handlers = [
+        h for h in logger.handlers if isinstance(h, logging.StreamHandler)
+    ]
+    assert len(stream_handlers) == 1
+    assert logger.level == logging.DEBUG
+
+
+def test_enable_logging_invalid_level_raises(reset_rocketpy_logger):
+    """enable_logging() must raise ValueError for an unrecognised level string."""
+    with pytest.raises(ValueError, match="Invalid logging level"):
+        utilities.enable_logging(level="INVALID")
+
+
+def test_enable_logging_messages_are_captured(reset_rocketpy_logger, caplog):
+    """After enable_logging(), internal rocketpy log messages must be visible."""
+    utilities.enable_logging(level="DEBUG")
+
+    with caplog.at_level(logging.DEBUG, logger="rocketpy"):
+        logger = logging.getLogger("rocketpy.simulation.flight")
+        logger.info("test message from flight")
+
+    assert "test message from flight" in caplog.text