astrocook.core.session module#

astrocook.core.session.load_session_from_file(archive_path: str, name: str, gui_context: Any, format_name: str) → SessionV2 | None[source]#

Orchestrate the loading of a session from a file or archive.

This function handles various input formats, including legacy Astrocook V1 archives (.acs), modern V2 archives (.acs2), and raw FITS files. It automatically handles V1-to-V2 migration of structures.

Parameters:

  • archive_path (str) – The full path to the file to load.

  • name (str) – The display name to assign to the new session.

  • gui_context (Any) – A reference to the main GUI window (for logging and dialog parenting), or a mock object if running in a script.

  • format_name (str) – A format identifier string (e.g., 'generic_spectrum', 'eso_midas') used to select the appropriate loader for raw files. Use 'auto' to attempt detection.

Returns:

The loaded SessionV2 object if successful. Returns 0 (integer) if the loading process failed.

Return type:

SessionV2 or int

Raises:

  • FileNotFoundError – If the archive path is invalid or internal files are missing.

  • RuntimeError – If the V1 archive unpacking fails.

class astrocook.core.session.SessionV2(name: str, gui: Any, spec: SpectrumV2 | None = None, systs: SystemListV2 | None = None)[source]#

Bases: object

The central coordinator for an Astrocook analysis session.

This class encapsulates the state of a single spectrum and its associated models (systems, components). It serves as the primary entry point for high-level analysis workflows (“Recipes”).

Note

Immutability Pattern: In Astrocook V2, the SessionV2 object is designed to be treated as immutable within the undo/redo history stack. Operations that modify data (like smoothing flux or fitting a continuum) do not modify the object in-place; instead, they return a new SessionV2 instance containing the updated data structures.

name#

The display name of the session (e.g., filename without extension).

Type:

str

systs#

The container for identified absorption systems and Voigt profile components.

Type:

astrocook.core.system_list.SystemListV2, optional

file#

Access to file import/export recipes (e.g., import_ascii, export_ascii).

Type:

astrocook.recipes.file.RecipeFileV2

edit#

Access to editing recipes (e.g., set_properties, convert_x_axis).

Type:

astrocook.recipes.edit.RecipeEditV2

flux#

Access to flux manipulation recipes (e.g., smooth, rebin).

Type:

astrocook.recipes.flux.RecipeFluxV2

continuum#

Access to continuum estimation and fitting recipes.

Type:

astrocook.recipes.continuum.RecipeContinuumV2

absorbers#

Access to line identification and fitting recipes.

Type:

astrocook.recipes.absorbers.RecipeAbsorbersV2

__init__(name: str, gui: Any, spec: SpectrumV2 | None = None, systs: SystemListV2 | None = None)[source]#
property spec: SpectrumV2 | None#

The main container for spectral data (flux, wavelength, error, etc.).

property lines#
classmethod open_new(file_path: str, name: str, gui_context: Any, format_name: str) → SessionV2[source]#

Factory method: Create a new SessionV2 by loading data from a file.

Parameters:

  • file_path (str) – The system path to the file (FITS or ACS/ACS2 archive).

  • name (str) – The name to give the new session.

  • gui_context (Any) – The GUI parent object (used for logging/dialogs).

  • format_name (str) – Hint for the file format loader (e.g. 'generic_spectrum').

Returns:

A new SessionV2 instance, or 0 on failure.

Return type:

SessionV2 or int

with_new_spectrum(new_spectrum: SpectrumV2) → SessionV2[source]#

Return a new SessionV2 instance with an updated spectrum.

This is used by recipes that modify spectral data (e.g., smoothing, continuum fitting) to ensure history preservation.

Parameters:

new_spectrum (SpectrumV2) – The new spectral data object.

Returns:

A shallow copy of the session pointing to the new spectrum.

Return type:

SessionV2

with_new_system_list(new_systs: SystemListV2) → SessionV2[source]#

Return a new SessionV2 instance with an updated system list.

Parameters:

new_systs (SystemListV2) – The new system list object.

Returns:

A shallow copy of the session pointing to the new system list.

Return type:

SessionV2

save(file_path: str, initial_session: SessionV2 | None = None, models: bool = False)[source]#

Save the current session state to a file.

This method supports two formats:

  1. .acs2 (Recommended): A zipped archive containing the full session state, metadata, and (optionally) the original data if initial_session is provided.

  2. .acs (Legacy): A folder-based or zipped structure compatible with Astrocook V1.

Parameters:

  • file_path (str) – The destination path. The extension (.acs vs .acs2) determines the format.

  • initial_session (SessionV2, optional) – The state of the session before any modifications. This is required when saving to .acs2 format to ensure the archive contains the original raw data for reproducibility.

  • models (bool, optional) – Flag for V1 backward compatibility (unused in V2 native saves).

Returns:

Returns 0 on success.

Return type:

int