Snakepit.PythonVersion (Snakepit v0.6.10)

Python version detection and compatibility checking.

This module detects the Python version and provides recommendations for which worker profile to use based on Python capabilities.

Python 3.13+ Free-Threading

Python 3.13 introduced experimental free-threading mode (PEP 703), removing the Global Interpreter Lock (GIL). This enables true multi-threaded parallelism within a single Python process.

Usage

# Detect Python version
{:ok, {3, 13, 0}} = Snakepit.PythonVersion.detect()

# Check free-threading support
true = Snakepit.PythonVersion.supports_free_threading?({3, 13, 0})

# Get profile recommendation
:thread = Snakepit.PythonVersion.recommend_profile()

Version Support

Python 3.8-3.12: Use :process profile (GIL present)
Python 3.13+: Can use :thread profile (free-threading available)

Summary

Types

profile()

version()

Functions

detect(executable \\ "python3")

Detect the Python version.

get_info(executable \\ "python3")

Get detailed Python environment information.

meets_requirements?(arg)

Check if the current Python version meets minimum requirements.

recommend_profile()

Recommend a worker profile based on the detected Python version.

recommend_profile(version)

supports_free_threading?(arg)

Check if a Python version supports free-threading mode.

validate()

Validate Python environment and provide warnings if needed.

Types

profile()

@type profile() :: :process | :thread

version()

@type version() ::
  {major :: non_neg_integer(), minor :: non_neg_integer(),
   patch :: non_neg_integer()}

Functions

detect(executable \\ "python3")

@spec detect(executable :: String.t()) :: {:ok, version()} | {:error, term()}

Detect the Python version.

Returns {:ok, {major, minor, patch}} or {:error, reason}.

Examples

iex> Snakepit.PythonVersion.detect()
{:ok, {3, 12, 0}}

iex> Snakepit.PythonVersion.detect("python3.13")
{:ok, {3, 13, 0}}

get_info(executable \\ "python3")

@spec get_info(executable :: String.t()) :: {:ok, map()} | {:error, term()}

Get detailed Python environment information.

Returns a map with version info, capabilities, and recommendations.

Examples

iex> Snakepit.PythonVersion.get_info()
{:ok, %{
  version: {3, 13, 0},
  version_string: "Python 3.13.0",
  supports_free_threading: true,
  recommended_profile: :thread,
  gil_status: "removable"
}}

meets_requirements?(arg)

@spec meets_requirements?(version()) :: boolean()

Check if the current Python version meets minimum requirements.

Snakepit requires Python 3.8 or higher.

Examples

iex> Snakepit.PythonVersion.meets_requirements?({3, 8, 0})
true

iex> Snakepit.PythonVersion.meets_requirements?({3, 7, 0})
false

recommend_profile()

@spec recommend_profile() :: profile()

Recommend a worker profile based on the detected Python version.

Python 3.8-3.12: Returns :process (GIL compatibility)
Python 3.13+: Returns :thread (free-threading capable)
Cannot detect: Returns :process (safe default)

Examples

iex> Snakepit.PythonVersion.recommend_profile()
:thread  # if Python 3.13+ detected

iex> Snakepit.PythonVersion.recommend_profile({3, 12, 0})
:process

recommend_profile(version)

@spec recommend_profile(version()) :: profile()

supports_free_threading?(arg)

@spec supports_free_threading?(version()) :: boolean()

Check if a Python version supports free-threading mode.

Free-threading (no-GIL mode) is available in Python 3.13+.

Examples

iex> Snakepit.PythonVersion.supports_free_threading?({3, 13, 0})
true

iex> Snakepit.PythonVersion.supports_free_threading?({3, 12, 0})
false

validate()

@spec validate() :: :ok | {:warning, [String.t()]}

Validate Python environment and provide warnings if needed.

Returns :ok if environment is valid, or {:warning, messages} if there are compatibility concerns.

Examples

iex> Snakepit.PythonVersion.validate()
:ok

iex> Snakepit.PythonVersion.validate()
{:warning, ["Python 3.7 detected. Snakepit requires Python 3.8+"]}