mnt/extract flight data exporters

CHANGELOG.md

@@ -39,6 +39,9 @@ Attention: The newest changes should be on top -->
 
 ### Changed
 
+- DOC: Update examples to use `FlightDataExporter` and add deprecation notes for legacy `Flight.export_*` methods. (#XXXX)
+- DEP: `Flight.export_data`, `Flight.export_pressures`, `Flight.export_sensor_data`, and `Flight.export_kml` are deprecated. Use `rocketpy.simulation.flight_data_exporter.FlightDataExporter.export_*`. Planned removal in v1.12.0. (#XXXX)
+- MNT: Extract `Flight.export_data`, `export_pressures`, `export_sensor_data`, and `export_kml` into `rocketpy.simulation.flight_data_exporter.FlightDataExporter` (no behavior change). (#XXXX)
 - ENH: _MotorPrints inheritance - issue #460 [#828](https://github.com/RocketPy-Team/RocketPy/pull/828)
 - MNT: fix deprecations and warnings [#829](https://github.com/RocketPy-Team/RocketPy/pull/829)
 

docs/user/first_simulation.rst

@@ -559,19 +559,27 @@ Visualizing the Trajectory in Google Earth
 
 We can export the trajectory to ``.kml`` to visualize it in Google Earth:
 
+Use the dedicated exporter class:
+
 .. jupyter-input::
 
-    test_flight.export_kml(
+    from rocketpy.simulation import FlightDataExporter
+
+    FlightDataExporter(test_flight).export_kml(
         file_name="trajectory.kml",
         extrude=True,
-        altitude_mode="relative_to_ground",
+        altitude_mode="relativetoground",
     )
 
 .. note::
 
     To learn more about the ``.kml`` format, see
     `KML Reference <https://developers.google.com/kml/documentation/kmlreference>`_.
 
+.. note::
+
+    The legacy method ``Flight.export_kml`` is deprecated. Use
+    :meth:`rocketpy.simulation.flight_data_exporter.FlightDataExporter.export_kml`.
 
 Manipulating results
 --------------------
@@ -604,29 +612,41 @@ In this section, we will explore how to export specific data from your RocketPy
 simulations to CSV files. This is particularly useful if you want to insert the
 data into spreadsheets or other software for further analysis.
 
-The main method that is used to export data is the :meth:`rocketpy.Flight.export_data` method. This method exports selected flight attributes to a CSV file. In this first example, we will export the rocket angle of attack (see :meth:`rocketpy.Flight.angle_of_attack`) and the rocket mach number (see :meth:`rocketpy.Flight.mach_number`) to the file ``calisto_flight_data.csv``.
+The recommended API is
+:meth:`rocketpy.simulation.flight_data_exporter.FlightDataExporter.export_data`,
+which exports selected flight attributes to a CSV file. In this first example,
+we export the rocket angle of attack (see :meth:`rocketpy.Flight.angle_of_attack`)
+and the rocket Mach number (see :meth:`rocketpy.Flight.mach_number`) to the file
+``calisto_flight_data.csv``.
 
 .. jupyter-execute::
 
-    test_flight.export_data(
+    from rocketpy.simulation import FlightDataExporter
+
+    exporter = FlightDataExporter(test_flight)
+    exporter.export_data(
         "calisto_flight_data.csv",
         "angle_of_attack",
         "mach_number",
     )
 
-| As you can see, the first argument of the method is the name of the file to be created. The following arguments are the attributes to be exported. We can check the file that was created by reading it with the :func:`pandas.read_csv` function:
+| As you can see, the first argument is the file name to be created. The following
+arguments are the attributes to be exported. We can check the file by reading it
+with :func:`pandas.read_csv`:
 
 .. jupyter-execute::
 
     import pandas as pd
 
     pd.read_csv("calisto_flight_data.csv")
 
-| The file header specifies the meaning of each column. The time samples are obtained from the simulation solver steps. Should you want to export the data at a different sampling rate, you can use the ``time_step`` argument of the :meth:`rocketpy.Flight.export_data` method as follows.
+| The file header specifies the meaning of each column. The time samples are
+obtained from the simulation solver steps. To export the data at a different
+sampling rate, use the ``time_step`` argument:
 
 .. jupyter-execute::
 
-    test_flight.export_data(
+    exporter.export_data(
         "calisto_flight_data.csv",
         "angle_of_attack",
         "mach_number",
@@ -635,24 +655,29 @@ The main method that is used to export data is the :meth:`rocketpy.Flight.export
 
     pd.read_csv("calisto_flight_data.csv")
 
-This will export the same data at a sampling rate of 1 second. The flight data will be interpolated to match the new sampling rate.
+This exports the same data at a sampling rate of 1 second. The flight data is
+interpolated to match the new sampling rate.
 
-Finally, the :meth:`rocketpy.Flight.export_data` method also provides a convenient way to export the entire flight solution (see :meth:`rocketpy.Flight.solution_array`) to a CSV file. This is done by not passing any attributes names to the method.
+Finally, ``FlightDataExporter.export_data`` also provides a convenient way to
+export the entire flight solution (see :meth:`rocketpy.Flight.solution_array`)
+by not passing any attribute names:
 
 .. jupyter-execute::
 
-    test_flight.export_data(
-        "calisto_flight_data.csv",
-    )
+    exporter.export_data("calisto_flight_data.csv")
 
 .. jupyter-execute::
     :hide-code:
     :hide-output:
 
     # Sample file cleanup
-    import os
+    import ospython.exe -m pip install --upgrade pip
     os.remove("calisto_flight_data.csv")
 
+.. note::
+
+    The legacy method ``Flight.export_data`` is deprecated. Use
+    :meth:`rocketpy.simulation.flight_data_exporter.FlightDataExporter.export_data`.
 
 Saving and Storing Plots
 ------------------------

rocketpy/simulation/__init__.py

@@ -2,3 +2,4 @@
 from .flight_data_importer import FlightDataImporter
 from .monte_carlo import MonteCarlo
 from .multivariate_rejection_sampler import MultivariateRejectionSampler
+from .flight_data_exporter import FlightDataExporter