refactor: Group session classes in separate package

[prmukherj]

Context

Some parts of the PyFluent code can be better grouped together, for example the sessions, for better rendering of the api docs.

Change Summary

1. All solver, meshing and File Session related files are grouped together in the sessions dir.

2. Proper module docstring and exposure to api docs.

3. the unexposed modules have been renamed to be private.

4. The complex inheritance structure of the PureMeshing getting derived from BaseSession directly has been resolved into BaseSession -> BaseMeshing -> PureMeshing and Meshing , similar structure to the solver.

5. All import paths modified.

Rationale

To better render api reference.

Impact

No impact to usability, only the codebase is better structured and improved readability of the modules.

BaseSession  (private)
├── Solver                — full solver session
│   ├── SolverAero        — solver + Aero add-on
│   ├── SolverIcing       — solver + Icing add-on
│   └── SolverLite        — lightweight solver variant
└── BaseMeshing  (private)   — full public meshing API
    ├── PureMeshing       — meshing-only (no solver switching)
    └── Meshing           — meshing with :meth:`~Meshing.switch_to_solver`

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[Copilot]

Pull request overview

This PR groups solver, meshing, and file sessions under ansys.fluent.core.session, refactors meshing inheritance, and updates related imports and documentation.

Changes:

• Introduces grouped session modules and private base classes.
• Updates imports, tests, launchers, settings, and API documentation support.
• Defers optional h5py imports and updates CI scheduling.

Reviewed changes

Copilot reviewed 34 out of 35 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Reviewed change / finding
tests/test_settings_api.py	Updates solver import.
tests/test_session.py	Updates private base-session import. Moderate (2 votes): patch the private parser module/function actually used by the launcher; the package no longer exports _parse_server_info_file.
tests/test_public_api.py	Adjusts public API expectations.
tests/test_physical_quantities.py	Updates file-session import.
tests/test_meshingmode/test_meshing_launch.py	Updates meshing help assertion.
tests/test_launcher_remote.py	Updates session imports.
tests/test_file_session.py	Updates file-session imports.
src/ansys/fluent/core/utils/setup_for_fluent.py	Uses the grouped solver module.
src/ansys/fluent/core/session/solver.py	Updates solver structure and documentation.
src/ansys/fluent/core/session/solver_lite.py	Updates lightweight solver structure.
src/ansys/fluent/core/session/solver_icing.py	Updates Icing solver structure.
src/ansys/fluent/core/session/solver_aero.py	Updates Aero solver structure.
src/ansys/fluent/core/session/pure_meshing.py	Adds the reorganized pure-meshing session. Moderate (2 votes): preserve the previous positional legacy argument contract for load_workflow and create_workflow.
src/ansys/fluent/core/session/meshing.py	Updates meshing inheritance and imports.
src/ansys/fluent/core/session/file.py	Relocates the file-session implementation.
src/ansys/fluent/core/session/_utilities.py	Updates session utility references.
src/ansys/fluent/core/session/_shared.py	Adds shared session helpers.
src/ansys/fluent/core/session/_session.py	Adds the private base-session module.
src/ansys/fluent/core/session/_base_meshing.py	Makes base meshing inherit from base session.
src/ansys/fluent/core/session/__init__.py	Defines the session package API and hierarchy. Nit (4 votes): update documentation generators and references to deleted module paths. Moderate (3 votes): preserve old import paths with shims or explicitly treat the change as breaking.
src/ansys/fluent/core/session_pure_meshing.py	Removes the superseded module.
src/ansys/fluent/core/services/settings.py	Centralizes interactive-mode behavior.
src/ansys/fluent/core/launcher/standalone_launcher.py	Updates type imports.
src/ansys/fluent/core/launcher/slurm_launcher.py	Updates session imports.
src/ansys/fluent/core/launcher/server_info.py	Uses the private parser module.
src/ansys/fluent/core/launcher/pim_launcher.py	Updates session imports.
src/ansys/fluent/core/launcher/launcher.py	Updates session imports.
src/ansys/fluent/core/launcher/launch_options.py	Updates session type mappings.
src/ansys/fluent/core/launcher/fluent_container.py	Uses the private parser module.
src/ansys/fluent/core/launcher/container_launcher.py	Updates session imports.
src/ansys/fluent/core/filereader/data_file.py	Lazily imports h5py. Moderate (2 votes): prevent the broad handler from masking ModuleNotFoundError with a generic runtime error.
src/ansys/fluent/core/filereader/case_file.py	Lazily imports h5py. Moderate (2 votes): prevent the broad handler from masking ModuleNotFoundError with a generic runtime error.
src/ansys/fluent/core/__init__.py	Updates package exports.
doc/changelog.d/5343.miscellaneous.md	Records the session grouping change.
.github/workflows/test-run-dev-version-nightly.yml	Changes the nightly schedule.

Suppressed comments (3)

src/ansys/fluent/core/launcher/launcher.py:74

• The runtime imports now use the grouped package, but this module's launch_fluent return docstring still links to deleted ansys.fluent.core.session_* modules (lines 379-382). Sphinx will emit broken cross-references for the public launcher API; update those targets to ansys.fluent.core.session.meshing, .pure_meshing, .solver, and .solver_icing.

from ansys.fluent.core.session.meshing import Meshing
from ansys.fluent.core.session.pure_meshing import PureMeshing
from ansys.fluent.core.session.solver import Solver
from ansys.fluent.core.session.solver_aero import SolverAero
from ansys.fluent.core.session.solver_icing import SolverIcing

src/ansys/fluent/core/launcher/slurm_launcher.py:103

• The runtime imports now use the grouped package, but this module's public future/result docstrings still link to deleted ansys.fluent.core.session_* modules (lines 348-351 and 551-554). Sphinx will emit broken cross-references; update those targets to the corresponding ansys.fluent.core.session.* modules.

from ansys.fluent.core.session.meshing import Meshing
from ansys.fluent.core.session.pure_meshing import PureMeshing
from ansys.fluent.core.session.solver import Solver
from ansys.fluent.core.session.solver_aero import SolverAero
from ansys.fluent.core.session.solver_icing import SolverIcing

src/ansys/fluent/core/session/init.py:30

• FileSession is one of the concrete classes re-exported below, but it is instantiated directly for offline file reading and is not created by launch_fluent. This new package docstring should limit the launcher statement to live sessions or explicitly mention FileSession.

The two non-user-facing base classes (``BaseSession``, ``BaseMeshing``) live in
private modules and must not be instantiated directly.  All concrete session
objects are created via :func:`ansys.fluent.core.launch_fluent`.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 42 out of 43 changed files in this pull request and generated 4 comments.

Suppressed comments (8)

src/ansys/fluent/core/init.py:46

• Removing the old session modules means pyfluent.session_solver is no longer an attribute of the package. The example examples/00-fluent/lunar_lander_thermal.py:238 evaluates pyfluent.session_solver.Solver at function definition time (it has no postponed-annotation import), so importing that example now raises AttributeError. Update that annotation to pyfluent.session.solver.Solver or retain a compatibility module attribute.

from ansys.fluent.core.session import *
from ansys.fluent.core.session.session import BaseSession as Fluent
from ansys.fluent.core.session.utilities import *

src/ansys/fluent/core/session/init.py:30

• The package docstring states that all concrete session objects are created via launch_fluent, but FileSession is re-exported below and is intentionally constructed directly for offline use. This makes the new API overview incorrect; qualify the statement to live Fluent sessions or explicitly mention the FileSession exception.

The two non-user-facing base classes (``BaseSession``, ``BaseMeshing``) live in
private modules and must not be instantiated directly.  All concrete session
objects are created via :func:`ansys.fluent.core.launch_fluent`.

src/ansys/fluent/core/session/init.py:46

• These *Session aliases do not provide backward compatibility for the old public module imports: this refactor deletes modules such as ansys.fluent.core.file_session and ansys.fluent.core.session_solver, but adds no forwarding shims. Existing consumers using those paths therefore get ModuleNotFoundError, despite this new docstring's backward-compatibility claim and the stated no-usability impact. Add deprecated forwarding modules or explicitly treat this as a breaking API change.

Each concrete class is re-exported here with a ``Session`` suffix for backward
compatibility and convenience:

src/ansys/fluent/core/session/base_meshing.py:98

• This docstring says both leaf classes add no further public methods, but Meshing defines switch_to_solver() in meshing.py:56. The generated hierarchy page will therefore misdescribe the public API; distinguish PureMeshing from Meshing here.
  src/ansys/fluent/core/session/base_meshing.py:449
• meshing_workflow_new.get_current_workflow() calls the load_workflow_handle with only initialize=False when it discovers a workflow that was loaded outside this Python object. Making file_path mandatory here turns that path into a TypeError; the previous file_path=None default was required for this callback, since the new LoadWorkflow skips the actual load when initialize=False. Keep file_path optional (or change the callback to provide a path) so session.current_workflow continues to work for externally loaded workflows.
  src/ansys/fluent/core/session/session.py:107
• The direct-instantiation guard makes the existing tests/test_launcher_remote.py:139 construction raise TypeError before the test reaches FluentConnection.wait_process_finished(), which is the operation expected to raise UnsupportedRemoteFluentInstance. Update that caller to use a concrete session or the private _create_instance factory; otherwise this existing test fails after the guard is added.
  src/ansys/fluent/core/session/session.py:107
• Because core/__init__.py continues to export BaseSession as the public ansys.fluent.core.Fluent symbol, this identity check also makes pyfluent.Fluent(...) raise the new TypeError. The public alias was constructible before this change and remains in the public API tests. Either remove/deprecate that export and update the API contract, or provide a constructible compatibility class instead of guarding the aliased class.
  tests/test_launcher_remote.py:51
• This import now refers to a class that deliberately rejects direct construction, but the test still calls BaseSession(...) later at line 139. If this test is enabled, the new guard raises TypeError instead of the expected UnsupportedRemoteFluentInstance; construct a concrete session or use the private test factory there.

[Copilot]

Pull request overview

Copilot reviewed 42 out of 43 changed files in this pull request and generated 4 comments.

Suppressed comments (8)

Previously missed (2) — in code that hasn't changed since the last review.

src/ansys/fluent/core/session/base_meshing.py:97

• This class docstring says both leaf classes add no further public methods, but Meshing explicitly adds the public switch_to_solver method (and documents it in meshing.py). That contradiction will misdescribe the key difference between Meshing and PureMeshing in the API reference; clarify that Meshing is the exception.
  doc/api_rstgen.py:76
• The generated API now enters through session/session_contents, but doc/deprecated_pyfluent_apis.py still links to ansys.fluent.core.session.BaseSession. BaseSession is no longer exported by this package (it lives in session.session, and that private module is not generated), so the deprecated-API roles will remain unresolved in the documentation build. Update these targets to a documented concrete session API or add the appropriate private-module documentation/alias.

    session/session_contents

.github/workflows/test-run-dev-version-nightly.yml:5

• This changes the nightly workflow from 03:00 to 01:00 UTC, which is unrelated to grouping session modules and changes CI resource scheduling. Unless this timing change is intentional, revert it or document its operational reason in the PR.

    - cron: "0 1 * * *"

src/ansys/fluent/core/init.py:77

• The runtime compatibility alias does not repair the generated API references: doc/deprecated_pyfluent_apis.py still targets ansys.fluent.core.file_session.*, while doc/api_rstgen.py now removes the file_session API page. The deprecated API table will therefore contain unresolved roles even though the old import may work; update those references or retain a compatibility API page.

_sys.modules["ansys.fluent.core.file_session"] = ansys_fluent_core_session_file

src/ansys/fluent/core/session/init.py:70

• Because this package no longer re-exports BaseSession, the existing entries in doc/deprecated_pyfluent_apis.py that target ansys.fluent.core.session.BaseSession.* now refer to a nonexistent object. Generating the deprecated API page will leave those Sphinx roles unresolved; update them to ansys.fluent.core.session.session.BaseSession or retain a compatibility package alias.

__all__ = [
    "MeshingSession",
    "PureMeshingSession",
    "SolverSession",
    "SolverAeroSession",

src/ansys/fluent/core/session/init.py:30

• This new package docstring links to ansys.fluent.core.launch_fluent, but the API generator documents the function from ansys.fluent.core.launcher.launcher and does not generate a top-level ansys.fluent.core automodule page. Use the canonical launcher module target so the session index does not introduce an unresolved cross-reference.

objects are created via :func:`ansys.fluent.core.launch_fluent`.

src/ansys/fluent/core/session/base_meshing.py:449

• BaseMeshing._get_current_workflow() passes self.load_workflow to meshing_workflow_new.get_current_workflow(), which invokes that callback as load_workflow_handle(initialize=False) when Fluent reports a loaded workflow. Making file_path required here therefore makes meshing.current_workflow raise TypeError for loaded workflows. Preserve the previous None default; the non-initializing path does not need a file path.
  src/ansys/fluent/core/session/session.py:107
• BaseSession is still exported as the public ansys.fluent.core.Fluent alias, so this new guard also makes pyfluent.Fluent(...) unusable. The public API test explicitly preserves Fluent, and it previously referred to this constructible class; either remove/deprecate that alias as a deliberate breaking change or preserve a compatible construction path before enforcing the guard.

[seanpearsonuk]

N.b. The branch name could have been refactor/... - we don't really do maint/....

[prmukherj]

N.b. The branch name could have been refactor/... - we don't really do maint/....

Thanks @seanpearsonuk,Noted.

[prmukherj]

https://github.com/ansys/pyfluent/actions/runs/33002461592