.. _python_api_versioning:

.. currentmodule:: flow360

.. rst-class:: indented-sections

**************
API Versioning
**************

Python API version numbers are directly associated with the Flow360 solver version you want to use. New projects created with the Python API will by default use the corresponding solver version.

For example if you want to use Flow360 solver version "release-25.8", you should install the Python API version "v25.8.*".

Cloud resources (project, geometry, surface mesh, volume mesh, case) and their configurations are backward compatible. Meaning that an old cloud resource can be loaded into any newer Python API version and/or submitted to any newer solver version. However forward compatibility is not guaranteed.

.. note::
   Cloud resources' versions are determined by the solver version they are created with. It is generally recommended to use the corresponding Python API version associated with the solver version you want to work with to avoid compatibility issues.

Install a specific version of the Python API
============================================

To install a specific version of Python API:

.. code-block:: bash

   pip install -U "flow360==25.8.*"

``-U`` moves to the newest 25.8 release even when an older 25.8 release is already installed; without it, pip reports "Requirement already satisfied" and keeps the older one.

Managing multiple versions
==========================

For users who need to work with multiple solver versions simultaneously, we recommend installing each version of the Python API in a separate isolated environment.
The examples below set up the Python API for both "release-25.12" and "release-25.11", with uv or with Conda.

uv (recommended)
----------------

With `uv <https://docs.astral.sh/uv/>`_ you do not create, activate or switch environments.
Instead, each script states the Python and Python API versions it needs in an
`inline metadata header <https://packaging.python.org/en/latest/specifications/inline-script-metadata/>`_:

.. code-block:: python

   # /// script
   # requires-python = "==3.11.*"
   # dependencies = ["flow360==25.12.*"]
   # ///
   import flow360 as fl

   ...

Keep the ``requires-python`` line: uv chooses the Python before it reads the Python API's own requirement and does not enforce that requirement's upper bound, so without the line a script can run on a Python version its release does not support.
Every 25.x release of the Python API supports Python 3.11.

Run every script with the same command, whichever version it targets:

.. code-block:: bash

   uv run submit_to_25.12.py
   uv run submit_to_25.11.py

On the first run, uv builds an isolated environment from the header, downloading that Python version if needed, and reuses the environment on later runs.

.. note::
   A script keeps the release it got on its first run, even after a newer 25.12 release is published.
   To move it to the newest one, run it once with ``-U``:

   .. code-block:: bash

      uv run -U submit_to_25.12.py

To run a script that has no header, pass the same versions on the command line:

.. code-block:: bash

   uv run --python 3.11 --with "flow360==25.11.*" submit_to_25.11.py

Conda
-----

Use Conda if you already work with it, or if you need a named environment to select in Jupyter or an IDE.

**1. Create and configure environment for Release 25.12**

.. code-block:: bash

   # Create a new conda environment named 'flow360-25.12' with its own Python
   conda create -n flow360-25.12 python=3.11 -y

   # Activate the environment
   conda activate flow360-25.12

   # Install the specific version of Flow360 API
   pip install "flow360==25.12.*"

**2. Create and configure environment for Release 25.11**

.. code-block:: bash

   # Create a new conda environment named 'flow360-25.11' with its own Python
   conda create -n flow360-25.11 python=3.11 -y

   # Activate the environment
   conda activate flow360-25.11

   # Install the specific version of Flow360 API
   pip install "flow360==25.11.*"

**3. List available virtual environments**

.. code-block:: bash

   conda env list

You should see the following output:

.. code-block:: bash

   # conda environments:
   #
   # * -> active
   # + -> frozen
   base                     C:\ProgramData\miniconda3
   flow360-25.11        *   C:\Users\UserName\.conda\envs\flow360-25.11
   flow360-25.12            C:\Users\UserName\.conda\envs\flow360-25.12

**4. Switch between versions**

You can now easily switch between different API versions by activating the corresponding Conda environment:

.. code-block:: bash

   # Switch to 25.12 environment and use solver version "release-25.12"
   conda activate flow360-25.12

   python submit_to_25.12.py

   # Switch to 25.11 environment and use solver version "release-25.11"
   conda activate flow360-25.11

   python submit_to_25.11.py