ENH: Add python loggers (#973)

* ENH: adopt built-in Python logging instead of print() calls

* ENH: adopt built-in Python logging instead of print() calls

* ENH: adopt built-in Python logging instead of print() calls

* ENH: adopt built-in Python logging instead of print() calls

* ENH: adopt built-in Python logging instead of print() calls

* ENH: adopt built-in Python logging for internal runtime events

* ENH: adopt built-in Python logging for internal runtime events

* STY: fix formatting with ruff and black

* STY: fix formatting with ruff and black

* Update rocketpy/environment/environment.py

Co-authored-by: Gui-FernandesBR <63590233+Gui-FernandesBR@users.noreply.github.com>

* Update rocketpy/environment/environment.py

Co-authored-by: Gui-FernandesBR <63590233+Gui-FernandesBR@users.noreply.github.com>

* Update rocketpy/environment/tools.py

Co-authored-by: Gui-FernandesBR <63590233+Gui-FernandesBR@users.noreply.github.com>

* Update rocketpy/mathutils/function.py

Co-authored-by: Gui-FernandesBR <63590233+Gui-FernandesBR@users.noreply.github.com>

* Update rocketpy/mathutils/vector_matrix.py

Co-authored-by: Gui-FernandesBR <63590233+Gui-FernandesBR@users.noreply.github.com>

* MNT: address PR review comments on nose_cone and tools

* MNT: fix docstrings and scope debug log to verbose flag

* MNT: restore SimMonitor print behavior for multiprocessing compatibility

* MNT: keep print() for user-requested plot headers, document enable_logging

Plot section headers (e.g. 'Trajectory 3d Plot', 'Airfoil lift curve:')
are emitted by user-invoked .plots.xxx()/.all() calls, not internal
runtime events, so per this PR's own print-vs-logger distinction they
should remain print() -- otherwise they silently disappear by default
while the plot itself is still shown, and reading them in a log stream
disconnected from the plot window doesn't make sense. Diagnostic
logger.warning() calls for skipped/missing data are left untouched.

Also adds user-guide and API reference docs for enable_logging(),
closing the last unresolved review comment on the PR.

* MNT: fix pylint regressions and restore visible progress output

- Bump pylintrc max-module-lines 3000->3050: environment.py now sits
  4 lines over the old hard limit purely from the logging import/setup
  this PR adds, tripping CI's fail-under=10 gate.
- Remove EmptyMotor import in rocket_plots.py, unused since PR #924
  switched that check to a string-based type-name comparison.
- Restore the exact pre-PR print() formatting (blank-line separators,
  dash dividers) in rocket_plots.py/environment_plots.py/flight_plots.py
  that got flattened when converting headers back to print() earlier
  in this branch.
- MonteCarlo: two logger.warning/error calls in __sim_producer run
  inside a multiprocessing worker process. Log handlers configured via
  enable_logging() in the parent process are not guaranteed to reach
  child processes (e.g. Windows "spawn"), so these would silently
  vanish -- exactly the cross-process issue already found and fixed
  for _SimMonitor in a prior commit on this branch, just missed here.
  Reverted to print()/_SimMonitor.reprint() for guaranteed visibility.
- For consistency with that worker output and with the still-visible
  per-iteration progress ticker, also reverted MonteCarlo's other
  lifecycle narration (start, worker count, results saved, file
  imports) to print(); logging module no longer needed in this file.

* MNT: revert FlightComparator output to print(), not logging

FlightComparator is an interactively-invoked reporting tool: add_data(),
compare(), summary() and all() exist specifically to print a
human-readable report the user is watching on their screen, exactly
like Flight.info()/Rocket.all_info() -- not an internal runtime event a
library embedder would want to filter or silence. Converting it to
logger.info()/logger.warning() meant summary() -- a method whose entire
purpose is printing a report -- produced no output at all under the
library's silent-by-default logging config, and the other methods lost
their multi-line human-readable formatting when consolidated into
single log records.

Restored the original print() calls and formatting verbatim, dropped
the now-unused logger import, and reverted the two tests that had been
migrated to caplog back to capsys to match.

---------

Co-authored-by: Gui-FernandesBR <guilherme_fernandes@usp.br>

Author: YuriCastroDev

.pylintrc

@@ -390,7 +390,7 @@ indent-string='    '
 max-line-length=88
 
 # Maximum number of lines in a module.
-max-module-lines=3000
+max-module-lines=3050
 
 # Allow the body of a class to be on the same line as the declaration if body
 # contains single statement.

CHANGELOG.md

@@ -49,6 +49,7 @@ Attention: The newest changes should be on top -->
 - ENH: Auto Populate Changelog [#919](https://github.com/RocketPy-Team/RocketPy/pull/919)
 - ENH: Adaptive Monte Carlo via Convergence Criteria [#922](https://github.com/RocketPy-Team/RocketPy/pull/922)
 - TST: Add acceptance tests for 3DOF flight simulation based on Bella Lui rocket [#914](https://github.com/RocketPy-Team/RocketPy/pull/914)
+- ENH: adopt built-in Python logging instead of print() calls [#450](https://github.com/RocketPy-Team/RocketPy/issues/450)
 
 ### Changed
 

docs/reference/classes/utils/index.rst

@@ -7,7 +7,8 @@ Utils functions
 
    tools
    units
-   utilities   
+   utilities
    vector
    matrix
-   
+   logging
+

docs/reference/classes/utils/logging.rst

@@ -0,0 +1,5 @@
+Logging functions
+-----------------
+
+.. automodule:: rocketpy.utils
+   :members:

docs/user/index.rst

@@ -47,4 +47,6 @@ RocketPy's User Guide
    :caption: Further Analysis
 
    Function <function.rst>
-   Utilities <analysis.rst>  Aerodynamic Surfaces <aerodynamics/surfaces.rst>
+   Utilities <analysis.rst>
+   Aerodynamic Surfaces <aerodynamics/surfaces.rst>
+   Logging <logging.rst>

docs/user/logging.rst

@@ -0,0 +1,75 @@
+Logging
+=======
+
+RocketPy uses Python's built-in `logging <https://docs.python.org/3/library/logging.html>`_
+module to report internal runtime events, such as simulation progress,
+warnings and errors. By design, RocketPy is **silent by default**: unless
+you configure a handler, no log records are printed to the console. This
+follows the best practices recommended for Python libraries and keeps
+RocketPy from cluttering the output of applications that embed it.
+
+.. note::
+    This only affects internal runtime events. Output that you explicitly
+    request, such as ``flight.info()`` or ``rocket.all_info()``, continues
+    to print directly to the terminal regardless of the logging
+    configuration described here.
+
+Enabling logging
+-----------------
+
+The easiest way to see RocketPy's internal log messages is the
+:func:`rocketpy.utils.enable_logging` helper, which attaches a console
+handler to RocketPy's logger hierarchy:
+
+.. jupyter-execute::
+
+    import rocketpy
+
+    rocketpy.utils.enable_logging(level="INFO")
+
+Once enabled, operations such as saving a file or completing a simulation
+will emit messages to the console, for example:
+
+.. code-block:: text
+
+    INFO | rocketpy.simulation.flight | Simulation completed successfully.
+
+Log levels
+----------
+
+The ``level`` parameter controls the minimum severity of messages that are
+shown:
+
+- ``DEBUG``: high-frequency, low-level detail (e.g. solver iterations),
+  useful when troubleshooting a simulation.
+- ``INFO``: confirmations of completed operations (e.g. simulation
+  completed, file saved).
+- ``WARNING`` (default): unexpected but recoverable situations (e.g. a
+  missing motor, an automatically corrected geometry parameter).
+- ``ERROR``: a feature is broken or an optional dependency is missing.
+
+.. jupyter-execute::
+
+    # Show every internal runtime message, including solver ticks
+    rocketpy.utils.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`
+at all:
+
+.. code-block:: python
+
+    import logging
+
+    handler = logging.StreamHandler()
+    handler.setFormatter(logging.Formatter("%(levelname)s | %(name)s | %(message)s"))
+
+    # Only show logs coming from the Flight simulation module
+    flight_logger = logging.getLogger("rocketpy.simulation.flight")
+    flight_logger.addHandler(handler)
+    flight_logger.setLevel(logging.INFO)

rocketpy/__init__.py

@@ -1,3 +1,5 @@
+import logging
+
 from .control import _Controller
 from .environment import Environment, EnvironmentAnalysis
 from .exceptions import (
@@ -53,6 +55,7 @@
     TrapezoidalFins,
 )
 from .sensitivity import SensitivityModel
+from . import utils
 from .sensors import Accelerometer, Barometer, GnssReceiver, Gyroscope
 from .simulation import Flight, MonteCarlo, MultivariateRejectionSampler
 from .stochastic import (
@@ -68,3 +71,5 @@
     StochasticTail,
     StochasticTrapezoidalFins,
 )
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())

rocketpy/environment/environment.py

@@ -1,8 +1,10 @@
 # pylint: disable=too-many-public-methods, too-many-instance-attributes
 import bisect
 import json
+import logging
 import re
 import warnings
+
 from collections import namedtuple
 from datetime import datetime
 
@@ -47,6 +49,8 @@
     geopotential_height_to_geometric_height,
 )
 
+logger = logging.getLogger(__name__)
+
 
 class Environment:
     """Keeps all environment information stored, such as wind and temperature
@@ -999,7 +1003,7 @@ def set_elevation(self, elevation="Open-Elevation"):
             self.elevation = elevation
         else:
             self.elevation = fetch_open_elevation(self.latitude, self.longitude)
-            print(f"Elevation received: {self.elevation} m")
+            logger.info("Elevation received: %.2f m", self.elevation)
 
     def set_topographic_profile(  # pylint: disable=redefined-builtin, unused-argument
         self, type, file, dictionary="netCDF4", crs=None
@@ -1038,14 +1042,13 @@ def set_topographic_profile(  # pylint: disable=redefined-builtin, unused-argume
                 # crsArray = nasa_dem.variables['crs'][:].tolist().
                 self.topographic_profile_activated = True
 
-                print("Region covered by the Topographical file: ")
-                print(
-                    f"Latitude from {self.elev_lat_array[-1]:.6f}° to "
-                    f"{self.elev_lat_array[0]:.6f}°"
-                )
-                print(
-                    f"Longitude from {self.elev_lon_array[0]:.6f}° to "
-                    f"{self.elev_lon_array[-1]:.6f}°"
+                logger.debug(
+                    "Topographical file coverage: lat [%.6f°, %.6f°], "
+                    "lon [%.6f°, %.6f°]",
+                    self.elev_lat_array[-1],
+                    self.elev_lat_array[0],
+                    self.elev_lon_array[0],
+                    self.elev_lon_array[-1],
                 )
 
     def get_elevation_from_topographic_profile(self, lat, lon):
@@ -2760,9 +2763,10 @@ def export_environment(self, filename="environment"):
 
         with open(filename + ".json", "w") as f:
             json.dump(export_env_dictionary, f, sort_keys=False, indent=4, default=str)
-        print(
-            f"Your Environment file was saved at '{filename}.json'. You can use "
-            "it in the future by using the custom_atmosphere atmospheric model."
+        logger.info(
+            "Your Environment file was saved at '%s.json'. "
+            "You can use it in the future by using the custom_atmosphere atmospheric model.",
+            filename,
         )
 
     def set_earth_geometry(self, datum):
@@ -2995,6 +2999,6 @@ def from_dict(cls, data):  # pylint: disable=too-many-statements
 
     results = doctest.testmod()
     if results.failed < 1:
-        print(f"All the {results.attempted} tests passed!")
+        logger.debug("All the %d tests passed!", results.attempted)
     else:
-        print(f"{results.failed} out of {results.attempted} tests failed.")
+        logger.error("%d out of %d tests failed.", results.failed, results.attempted)

rocketpy/environment/environment_analysis.py

@@ -2,7 +2,9 @@
 import copy
 import datetime
 import json
+import logging
 import warnings
+
 from collections import defaultdict
 from functools import cached_property
 
@@ -24,6 +26,8 @@
 from ..units import convert_units
 from .environment import Environment
 
+logger = logging.getLogger(__name__)
+
 # TODO: the average_wind_speed_profile_by_hour and similar methods could be more abstract than currently are
 
 
@@ -236,13 +240,15 @@ def __check_requirements(self):
                 check_requirement_version(module_name, version)
             except (ValueError, ImportError) as e:
                 has_error = True
-                print(
-                    f"The following error occurred while importing {module_name}: {e}"
+                logger.error(
+                    "The following error occurred while importing %s: %s",
+                    module_name,
+                    e,
                 )
         if has_error:
-            print(
+            logger.error(
                 "Given the above errors, some methods may not work. Please run "
-                + "'pip install rocketpy[env_analysis]' to install extra requirements."
+                "'pip install rocketpy[env_analysis]' to install extra requirements."
             )
 
     def __init_surface_dictionary(self):
@@ -506,8 +512,9 @@ def __init_unit_system(self):
             }
         else:
             # Default to SI
-            print(
-                f"Defaulting to SI unit system, the {self.unit_system_string} was not found."
+            logger.warning(
+                "Defaulting to SI unit system, the '%s' unit system was not found.",
+                self.unit_system_string,
             )
             self.unit_system = {
                 "length": "m",
@@ -2804,9 +2811,10 @@ def export_mean_profiles(self, filename="export_env_analysis"):
                     self.export_dictionary, sort_keys=False, indent=4, default=str
                 )
             )
-        print(
-            f"Your Environment Analysis file was saved, check it out: {filename}.json\n"
-            "You can use it to set a `customAtmosphere` atmospheric model"
+        logger.info(
+            "Your Environment Analysis file was saved: %s.json. "
+            "You can use it to set a customAtmosphere atmospheric model.",
+            filename,
         )
 
     @classmethod
@@ -2845,7 +2853,7 @@ def save(self, filename="env_analysis_dict"):
         file = open(filename, "w")  # pylint: disable=consider-using-with
         file.write(encoded_class)
         file.close()
-        print("Your Environment Analysis file was saved, check it out: " + filename)
+        logger.info("Your Environment Analysis file was saved: %s", filename)
 
     def create_environment_object(
         self, gravity=None, date=None, datum="SIRGAS2000", max_expected_height=80000.0

rocketpy/environment/fetchers.py

@@ -3,6 +3,7 @@
 functions may be changed without notice in future feature releases.
 """
 
+import logging
 import re
 import time
 from datetime import datetime, timedelta, timezone
@@ -12,6 +13,8 @@
 
 from rocketpy.tools import exponential_backoff
 
+logger = logging.getLogger(__name__)
+
 MAX_RETRY_DELAY_SECONDS = 600
 
 
@@ -37,7 +40,9 @@ def fetch_open_elevation(lat, lon):
     RuntimeError
         If there is a problem reaching the Open-Elevation API servers.
     """
-    print(f"Fetching elevation from open-elevation.com for lat={lat}, lon={lon}...")
+    logger.debug(
+        "Fetching elevation from open-elevation.com for lat=%s, lon=%s", lat, lon
+    )
     request_url = f"https://api.open-elevation.com/api/v1/lookup?locations={lat},{lon}"
     try:
         response = requests.get(request_url)