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 chemapp.friendly.Info class provides methods for managing update settings and configuring the package behavior.

You can call Info.check_for_updates(force=True) to bypass the cooldown and run an immediate check.

Configuration API

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.

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 Info.set_density_config() and can be queried with Info.read_density_config().

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:

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.