FABulous.FABulous_settings
==========================

.. py:module:: FABulous.FABulous_settings

.. autoapi-nested-parse::
   FABulous settings management and environment configuration.

   This module handles configuration settings for the FABulous FPGA framework, including
   tool paths, project settings, and environment variable management.



Classes
-------

.. py:class:: FABulousSettings()

   **Bases:** 

   FABulous settings.

   Tool paths are resolved lazily during validation so that environment variable setup
   (including PATH updates for oss-cad-suite) can occur beforehand.



   **Methods:**

   .. py:method:: ensure_user_config_dir(value)

      Ensure user config directory exists, creating if necessary.


   .. py:method:: is_valid_project_dir(value)

      Check if project_dir is a valid directory.


   .. py:method:: parse_model_pack(value, info)

      Validate and normalise model_pack path based on project language.

      Uses already-validated proj_lang from info.data when available. Accepts None /
      empty string to mean unset.


   .. py:method:: parse_version_str(value)

      Parse version from string or Version object.


   .. py:method:: resolve_tool_paths(value, info)

      Resolve tool paths by checking if tools are available in `PATH`.

      This method is used as a field validator to automatically resolve tool paths
      during settings initialization. If a tool path is not explicitly provided,
      it searches for the tool in the system `PATH`.

      :param value: The explicitly provided tool path, if any.
      :type value: Path | None
      :param info: Validation context containing field information.
      :type info: FieldValidationInfo

      :returns: The resolved path to the tool if found, `None` otherwise.
      :rtype: Path | None

      .. rubric:: Notes

      This method logs a warning if a tool is not found in `PATH`, as some
      features may be unavailable without the tool.


   .. py:method:: validate_proj_lang(value)

      Validate and normalise the project language to HDLType enum.



Functions
---------

.. py:function:: add_var_to_global_env(key, value)

Add or update a key-value pair to the global .env file.

   :param key: The environment variable key to add or update.
   :type key: str
   :param value: The value to set for the environment variable.
   :type value: str

   :raises RuntimeError: If the user config directory is not set.

.. py:function:: get_context()

Get the global FABulous context.

   :rtype: The current FABulousSettings instance

   :raises RuntimeError: If context has not been initialized with init_context():

.. py:function:: init_context(project_dir = None, global_dot_env = None, project_dot_env = None)

Initialize the global FABulous context with settings.

   This function gathers .env files and lets the pydantic-settings system handle
   project directory resolution.

   Args:
       global_dot_env: Global .env file path
       project_dot_env: Project .env file path
       explicit_project_dir: Explicitly provided project directory (highest priority)

   :rtype: The initialized FABulousSettings instance

.. py:function:: reset_context()

Reset the global context (primarily for testing).


Module Attributes
-----------------

.. py:data:: FAB_USER_CONFIG_DIR
   :no-index: