.. role:: new
   :class: new
.. _ch-update_and_configuration:

:new:`Update checks and persistent configuration`
=================================================

ChemApp for Python provides a lightweight mechanism to (a) periodically check
whether a newer package version is available and (b) persist user preferences
for that mechanism and for density / volume estimation behavior across Python
sessions by storing a configuration file in the user directory.


File location and format
------------------------

The configuration is stored in a plain text file named ``chemapp_python.cfg``
located in the user home directory returned by the Python standard library
(``Path.home()``). The file is created on first use of either configuration
routine if it does not yet exist, or at startup of ChemApp for Python. Existing
keys are updated in-place; unrelated user edits are ignored but preserved as
long as they do not collide with managed keys.

Currently persisted keys:

* ``cooldown_days`` - integer >= 0, days between automatic checks
* ``notify_level`` - one of ``major``, ``minor``, ``patch``
* ``disable`` - boolean (``true``/``false``) toggle for automatic checks
* ``last_check`` - timestamp of last completed (non-forced) check
* ``volume_estimate_setting`` - one of enum member names listed below

Update mechanism
----------------



When the package is imported, an automatic (non-forced) update check may be
performed if

1. Automatic checks are not disabled
2. The last successful check was performed more than ``cooldown_days`` many days ago.

The server is contacted only when both conditions hold. A successful request
returns metadata about the latest available version. If that version is newer
than the currently installed one and matches / exceeds the configured
``notify_level`` (semantic version precedence), a message is emitted (e.g.
stdout / logging) how to upgrade.

The :py:class:`chemapp.friendly.Info` class provides methods for
managing update settings and configuring the package behavior.

You can call :py:meth:`Info.check_for_updates(force=True) <chemapp.friendly.Info.check_for_updates>` to bypass
the cooldown and run an immediate check.

Configuration API
-----------------

:py:meth:`Info.set_update_check_config() <chemapp.friendly.Info.set_update_check_config>` accepts keyword arguments; omitted ones leave the
stored values unchanged. Validation errors (e.g. invalid ``notify_level``)
raise an exception before writing.

.. code-block:: python

   from chemapp.friendly import Info

   # Change only the cooldown and leave other values untouched.
   Info.set_update_check_config(cooldown_days=14)

   # Inspect current effective configuration
   cfg = Info.get_update_check_config()
   print(cfg)

Density / volume estimation preference
--------------------------------------

ChemApp can either rely on volume / density data embedded in the thermodynamic
datafile or use an estimation module. The behavior is configurable permanently
via :py:meth:`Info.set_density_config() <chemapp.friendly.Info.set_density_config>` and can be queried with
:py:meth:`Info.read_density_config() <chemapp.friendly.Info.read_density_config>`.

:py:class:`chemapp.core.VolumeEstimateSetting` members:

* ``ALWAYS`` - Always use the estimation module results even if the datafile
  already provides volume / density data (estimation overrides datafile).
* ``NEVER`` - Never use the estimation module; rely exclusively on datafile
  values when present.
* ``IFMISSING`` - Use estimation only for entries where the datafile does not
  supply volume / density; do not override existing datafile values.

Example:

.. code-block:: python

   from chemapp.friendly import Info
   from chemapp.core import VolumeEstimateSetting

   # Prefer datafile volumes; estimate only when absent
   Info.set_density_config(new_setting=VolumeEstimateSetting.IFMISSING)

   current = Info.read_density_config()
   print("Density setting:", current.name)

Operational notes
-----------------

* All configuration changes are process-safe in the sense that concurrent
  writes are last-one-wins; there is no locking. Avoid simultaneous writes
  from multiple processes if deterministic ordering is required; this can be 
  an issue if multiple ChemApp installations and environments are accessing 
  the settings at the same time.
* Invalid manual edits to ``chemapp_python.cfg`` may lead to fallback to
  defaults or raise errors when read; remove the offending lines to reset.
* Removing the file resets all settings to their package defaults on the next
  import.