Merge pull request #3166 from SasView/platfromdirs

Use platformdirs package for all user-related file paths

Author: krzywon

build_tools/requirements.txt

@@ -16,6 +16,7 @@ matplotlib
 numba
 numpy
 periodictable
+platformdirs
 pybind11
 pylint
 pyopengl

docs/sphinx-docs/build_sphinx.py

@@ -19,8 +19,6 @@
 from distutils.util import get_platform
 from distutils.spawn import find_executable
 
-from sas.system.user import get_user_dir
-
 platform = '.%s-%s'%(get_platform(),sys.version[:3])
 
 # sphinx paths

docs/sphinx-docs/source/user/working.rst

@@ -25,3 +25,5 @@ Working with SasView
    Model Marketplace <marketplace>
 
    Preferences <qtgui/MainWindow/preferences_help.rst>
+
+   User Files <qtgui/MainWindow/sasview_files>

installers/installer.iss

@@ -61,7 +61,7 @@ end;
 
 [Files]
 Source: "dist\sasview\sasview.exe"; DestDir: "{app}"; Flags: ignoreversion
-Source: "dist\sasview\plugin_models\*"; DestDir: "{%USERPROFILE}\.sasview\plugin_models"
+Source: "dist\sasview\plugin_models\*"; DestDir: "{%USERPROFILE}\AppData\Local\sasview\SasView\plugin_models"
 Source: "dist\sasview\*"; DestDir: "{app}"; Flags: ignoreversion recursesubdirs createallsubdirs
 
 [InstallDelete]

installers/sasview.spec

@@ -19,7 +19,6 @@ datas = [
     ('../src/sas/qtgui/Utilities/WhatsNew/messages', 'sas/qtgui/Utilities/WhatsNew/messages'),
     ('../src/sas/qtgui/Utilities/WhatsNew/css/style.css', 'sas/qtgui/Utilities/WhatsNew/css'),
     ('../src/sas/qtgui/Utilities/About/images', 'sas/qtgui/Utilities/About/images'),
-    ('../src/sas/system/log.ini', 'sas/system/'),
     ('../../sasmodels/sasmodels','sasmodels'),
     ('../docs/sphinx-docs/build','doc/build'),
     ('../docs/sphinx-docs/source-temp','doc/source')

src/sas/cli.py

@@ -104,6 +104,10 @@ def parse_cli(argv):
     return opts
 
 def main(logging="production"):
+    # Copy files before loading config
+    from sas.system.user import copy_old_files_to_new_location
+    copy_old_files_to_new_location()
+
     from sas.system import log
     from sas.system import lib
     from sas.system import console

src/sas/qtgui/MainWindow/media/sasview_files.rst

@@ -0,0 +1,108 @@
+.. sasview_files.rst
+
+.. Initial Draft: J Krzywon, Apr 2025
+.. Last Updated: J Krzywon, Apr. 9, 2025
+
+.. _UserFiles:
+
+SasView User Files
+==================
+
+During the installation process and while running the app, SasView creates a number of files that are stored outside
+the install location on the end users computer. These files include configurations, plugin models, compiled plugins,
+documentation, and example files. Please refer to the specific section to find where each type of file is stored.
+
+File paths that start with the '~' character refer to the user directory, which is typically `C:\\\\Users\\<username>` in
+Windows, `/Users/<username>` in MacOS, and `/home/<username>` in most Linux distributions.
+
+This document is specific to v6.1.0 and beyond. Previous versions of SasView stored user files in the
+`~/.sasview` directory.
+
+**For users who wish to use versions both newer and older than v6.1, do not delete the contents
+of the `~/.sasview` directory.**
+
+
+:ref:`Config_Files`, :ref:`Log_Files`, :ref:`Plugin_Files`, :ref:`Compiled_Files`, :ref:`Documentation`
+
+.. , :ref:`Example_Data`
+
+.. _Config_Files:
+
+Configuration Files
+--------------------
+SasView stores two types of config file on the user disk, a general configuration file for each major version of sasview,
+and a categories file that allows the end user to change how their models are organized in the fitting perspective. The
+general configuration file, config-<v>.json is a json file that stores a mapping of config variables to their updated values.
+This file is only generated and stored locally if something in the :ref:`Preferences` panel has been modified. The categories
+file, categories.json, stores the user-preferred model organization, allowing a user to add model categories, move models
+into new categories, and not show certain models. More information on this feature is available in :ref:`Category_Manager`.
+
+OS-specific file locations for configuration files:
+ - Windows: ~/AppData/Local/sasview/SasView/
+ - MacOS: ~/Library/Application Support/SasView/
+ - Linux: ~/.config/SasView/
+
+.. _Log_Files:
+
+Log Files
+---------
+SasView creates a time-stamped log file that includes all messages entered into the log explorer, as well as a number of
+other messages related to application startup and shutdown.
+
+OS-specific file locations for log files:
+ - Windows: ~/AppData/Local/sasview/SasView/Logs/
+ - MacOS: ~/Library/Logs/SasView/
+ - Linux: ~/.local/state/SasView/
+
+.. _Plugin_Files:
+
+Plugin Files
+------------
+Plugin models, whether they be written by the user (:ref:`Writing_a_Plugin`), downloaded from the
+`model marketplace <https://marketplace.sasview.org/>`_, or sent from another SasView user, should be stored in a
+specific location to allow SasView to find them.
+
+OS-specific file locations for plugin files:
+ - Windows: ~/AppData/Local/sasview/SasView/plugin_models/
+ - MacOS: ~/Library/Application Support/SasView/plugin_models/
+ - Linux: ~/.local/share/SasView/plugin_models
+
+.. _Compiled_Files:
+
+Complied Model Files
+------------
+The fitting module, when a model is selected, compiles each model in an on-demand process. The compiled file will include
+all form factors and structure factors used to create the model, and will be compiled based on the GPU optimization
+currently in use. These models are stored in a parallel directory to the plugin models, but end users do not need to add
+any files to this directory.
+
+OS-specific file locations for compiled model files:
+ - Windows: ~/AppData/Local/sasview/SasView/compiled_models/
+ - MacOS: ~/Library/Application Support/SasView/compiled_models/
+ - Linux: ~/.local/share/SasView/compiled_models
+
+.. _Documentation:
+
+Documentation
+-------------
+SasView moves its documentation into a user location when launching the app, if the documentation does not already exist.
+Each version of SasView has its own documentation that may be different between versions, so a separate directory is used
+for each version of the doc files.
+
+OS-specific file locations for documentation:
+ - Windows: ~/AppData/Local/sasview/SasView/<sasview.version>/doc/
+ - MacOS: ~/Library/Application Support/SasView/<sasview.version>/doc/
+ - Linux: ~/.local/share/SasView/<sasview.version>/doc/
+
+..
+.. _Example_Data:
+
+.. Example Data
+.. ------------
+.. SasView supplies a number of example data files that may be used to orient yourself with the application. More information
+.. on the included files is available at :ref:`example_data_help`. These files are moved to the user directory on install.
+
+.. OS-specific file locations for example data:
+.. - Windows: ~/AppData/Local/sasview/SasView/example_data/
+.. - MacOS: ~/Library/Application Support/SasView/example_data/
+.. - Linux: <TODO>

src/sas/qtgui/Utilities/CategoryInstaller.py

@@ -14,6 +14,8 @@
 import logging
 from collections import defaultdict, OrderedDict
 
+from sas.system.user import get_config_dir
+
 USER_FILE = 'categories.json'
 
 class CategoryInstaller:
@@ -31,7 +33,7 @@ def _get_home_dir():
         """
         returns the users sasview config dir
         """
-        return os.path.join(os.path.expanduser("~"), ".sasview")
+        return get_config_dir()
 
     @staticmethod
     def _regenerate_model_dict(master_category_dict):

src/sas/sascalc/doc_regen/makedocumentation.py

@@ -12,17 +12,16 @@
 from typing import Union
 
 from sas.sascalc.fit import models
-from sas.system.version import __version__
-from sas.system.user import get_user_dir
+from sas.system.user import get_app_dir_versioned
 
 from sasmodels.core import list_models
 
 PATH_LIKE = Union[Path, str, os.PathLike]
 
 # Path constants related to the directories and files used in documentation regeneration processes
-USER_DIRECTORY = Path(get_user_dir())
-USER_DOC_BASE = USER_DIRECTORY / "doc"
-USER_DOC_SRC = USER_DOC_BASE / str(__version__)
+APP_DIRECTORY = Path(get_app_dir_versioned())
+USER_DOC_BASE = APP_DIRECTORY / "doc"
+USER_DOC_SRC = USER_DOC_BASE
 USER_DOC_LOG = USER_DOC_SRC / 'log'
 DOC_LOG = USER_DOC_LOG / 'output.log'
 MAIN_DOC_SRC = USER_DOC_SRC / "source-temp"

src/sas/sascalc/doc_regen/regenmodel.py

@@ -413,7 +413,7 @@ def main():
         help="model files ")
     args = parser.parse_args()
 
-    TARGET_DIR = os.path.expanduser(args.rst)
+    TARGET_DIR = Path(TARGET_DIR / args.rst) if args.rst else TARGET_DIR
     if not os.path.exists(TARGET_DIR) and not args.sphinx:
         print("build directory %r does not exist"%TARGET_DIR)
         sys.exit(1)

src/sas/sascalc/fit/models.py

@@ -1,8 +1,6 @@
 """
     Utilities to manage models
 """
-from __future__ import print_function
-
 import os
 import sys
 import time
@@ -15,7 +13,7 @@
 
 from sasmodels.sasview_model import load_custom_model, load_standard_models
 
-from sas.system.user import get_user_dir
+from sas.system.user import get_plugin_dir
 
 # Explicitly import from the pluginmodel module so that py2exe
 # places it in the distribution. The Model1DPlugin class is used
@@ -26,7 +24,7 @@
 
 
 PLUGIN_DIR = 'plugin_models'
-PLUGIN_LOG = os.path.join(get_user_dir(), PLUGIN_DIR, "plugins.log")
+PLUGIN_LOG = os.path.join(get_plugin_dir(), "plugins.log")
 PLUGIN_NAME_BASE = '[plug-in] '
 
 
@@ -82,29 +80,14 @@ def _check_plugin(model, name):
     return model
 
 
-def find_plugins_dir():
-    """
-    Find path of the plugins directory.
-    The plugin directory is located in the user's home directory.
+def find_plugins_dir() -> str:
+    """A helper function that returns a string representation of the plugins directory as defined by sas.system.user.
     """
-    path = os.path.join(os.path.expanduser("~"), '.sasview', PLUGIN_DIR)
-
-    # TODO: trigger initialization of plugins dir from installer or startup
-    # If the plugin directory doesn't exist, create it
-    if not os.path.isdir(path):
-        os.makedirs(path)
-    # TODO: should we be checking for new default models every time?
-    # TODO: restore support for default plugins
-    #initialize_plugins_dir(path)
-    return path
+    return str(get_plugin_dir())
 
 
 def initialize_plugins_dir(path):
     # TODO: There are no default plugins
-    # TODO: Default plugins directory is in sasgui, but models.py is in sascalc
-    # TODO: Move default plugins beside sample data files
-    # TODO: Should not look for defaults above the root of the sasview install
-
     # Walk up the tree looking for default plugin_models directory
     base = os.path.abspath(os.path.dirname(__file__))
     for _ in range(12):

src/sas/system/config/config_meta.py

@@ -58,7 +58,7 @@ def defaults(self):
     def config_filename(self, create_if_nonexistent=False):
         """Filename for saving config items"""
         version_parts = sas.system.version.__version__.split(".")
-        user_dir = user.get_user_dir(create_if_nonexistent)
+        user_dir = user.get_config_dir(create_if_nonexistent)
         return os.path.join(user_dir, f"config-{version_parts[0]}.json")
 
     def finalise(self):

src/sas/system/lib.py

@@ -8,7 +8,7 @@
 # TODO: Add api to control sasmodels rather than using environment variables
 def setup_sasmodels():
     """Initialize sasmodels settings from the sasview configuration."""
-    from .user import get_user_dir
+    from .user import get_app_dir
 
     # Don't need to set SAS_MODELPATH for gui because sascalc.fit uses the
     # full paths to models, but when using the sasview package as a python
@@ -21,7 +21,7 @@ def setup_sasmodels():
     # Both scripts and gui need to know the stored DLL path.
     if "SAS_DLL_PATH" not in os.environ:
         os.environ["SAS_DLL_PATH"] = os.path.join(
-            get_user_dir(), "compiled_models")
+            get_app_dir(), "compiled_models")
 
     # Set OpenCL config from environment variable if it is set otherwise
     # use the value from the sas config file.

src/sas/system/log.ini

@@ -6,7 +6,7 @@
 import sys
 import os.path
 
-import importlib.resources
+from sas.system.user import get_log_dir
 
 '''
 Module that manages the global logging
@@ -42,12 +42,16 @@ def setup_logging(level=logging.INFO):
 
     # Apply the logging config after setting the defaults
     try:
-        fd = importlib.resources.open_text('sas.system', 'log.ini')
-        logging.config.fileConfig(fd)
-    except FileNotFoundError:
-        print(f"ERROR: Log config '{fd.name}' not found...", file=sys.stderr)
-
-    #print_config()
+        filename = os.path.join(get_log_dir(), 'sasview.log')
+        fh = logging.FileHandler(filename=filename, mode="a")
+    except IOError:
+        print(f"ERROR: Log config '{filename}' not found...", file=sys.stderr)
+        fh = None
+    ch = logging.StreamHandler()
+    handlers = [fh, ch] if fh else [ch]
+    logging.basicConfig(format='%(asctime)s : %(levelname)s : %(name)s (%(filename)s:%(lineno)s) :: %(message)s',
+                        handlers=handlers)
+    # print_config()
 
 def production():
     setup_logging('INFO')