Merge pull request #2981 from cphyc/migrate-config-to-toml

Migrate config to toml

conftest.py

@@ -56,7 +56,7 @@ def pytest_configure(config):
     each answer test's answer file (including the changeset number).
     """
 
-    ytcfg["yt", "__withinpytest"] = "True"
+    ytcfg["yt", "internals", "within_pytest"] = True
     # Make sure that the answers dir exists. If not, try to make it
     if not os.path.isdir(answer_dir):
         os.mkdir(answer_dir)

doc/helper_scripts/run_recipes.py

@@ -24,7 +24,7 @@
     "AMRGridData_Slice_x_density.png",
 ]
 CWD = os.getcwd()
-ytcfg["yt", "serialize"] = "False"
+ytcfg["yt", "serialize"] = False
 PARALLEL_TEST = {"rockstar_nest": "3"}
 BLACKLIST = ["opengl_ipython", "opengl_vr"]
 

doc/helper_scripts/show_fields.py

@@ -23,7 +23,7 @@
 base_ds.cosmology = Cosmology()
 
 
-ytcfg["yt", "__withintesting"] = "True"
+ytcfg["yt", "internals", "within_testing"] = True
 np.seterr(all="ignore")
 
 
@@ -202,7 +202,7 @@ def __init__(self, ftype, field, ptype):
             self.dname = f":math:`{field[1][2]}`"
 
         if ftype != "particle_type":
-            ftype = "'" + ftype + "'"
+            ftype = f"'{ftype}'"
         self.name = f"({ftype}, '{name}')"
         self.ptype = ptype
 

doc/source/developing/building_the_docs.rst

@@ -198,7 +198,7 @@ and build it using Sphinx:
 If all of the dependencies are installed and all of the test data is in the
 testing directory, this should churn away for a while (several hours) and
 eventually generate a docs build.  We suggest setting
-:code:`suppressStreamLogging = True` in your yt configuration (See
+:code:`suppress_stream_logging = True` in your yt configuration (See
 :ref:`configuration-file`) to suppress large amounts of debug output from
 yt.
 

doc/source/developing/testing.rst

@@ -240,7 +240,7 @@ project's contiguous integration server.
 This command will create a set of local answers from the tipsy frontend tests
 and store them in ``$HOME/Documents/test`` (this can but does not have to be the
 same directory as the ``test_data_dir`` configuration variable defined in your
-``~/.config/yt/ytrc`` file) in a file named ``local-tipsy``. To run the tipsy
+``~/.config/yt/yt.toml`` file) in a file named ``local-tipsy``. To run the tipsy
 frontend's answer tests using a different yt changeset, update to that
 changeset, recompile if necessary, and run the tests using the following
 command:

doc/source/faq/index.rst

@@ -379,10 +379,10 @@ unfamiliar, please visit :ref:`loading-data`.
 To make things easier to load these sample datasets, you can add the parent
 directory to your downloaded sample data to your *yt path*.
 If you set the option ``test_data_dir``, in the section ``[yt]``,
-in ``~/.config/yt/ytrc``, yt will search this path for them.
+in ``~/.config/yt/yt.toml``, yt will search this path for them.
 
 This means you can download these datasets to ``/big_drive/data_for_yt`` , add
-the appropriate item to ``~/.config/yt/ytrc``, and no matter which directory you are
+the appropriate item to ``~/.config/yt/yt.toml``, and no matter which directory you are
 in when running yt, it will also check in *that* directory.
 
 
@@ -428,11 +428,11 @@ especially if you are in an IPython notebook or running a long or parallel scrip
 On the other hand, you may want it to output a lot more, since you can't figure out
 exactly what's going wrong, and you want to output some debugging information.
 The default yt log level can be changed using the :ref:`configuration-file`,
-either by setting it in the ``$HOME/.config/yt/ytrc`` file:
+either by setting it in the ``$HOME/.config/yt/yt.toml`` file:
 
 .. code-block:: bash
 
-   $ yt config set yt loglevel 10  # This sets the log level to "DEBUG"
+   $ yt config set yt log_level 10  # This sets the log level to "DEBUG"
 
 which would produce debug (as well as info, warning, and error) messages, or at runtime:
 

doc/source/reference/command-line.rst

@@ -341,19 +341,21 @@ This will print the list of available subcommands:
 
 .. config_help:: yt config
 
-Since the yt version 3.3.2, the previous location of the configuration file
-(``$HOME/.yt/config``) has been deprecated in favor of a location adhering to the
+
+Since yt version 4, the configuration file is located in ``$XDG_CONFIG_HOME/yt/yt.toml`` adhering to the
 `XDG Base Directory Specification
 <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_.
-(``$XDG_HOME_CONFIG/yt/ytrc``). In order to perform an automatic migration of
-the old config, you are encouraged to run:
+Unless customized, this defaults to ``$HOME/.config/`` on Unix-like systems (macOS, Linux, ...).
+The old configuration file (``$XDG_CONFIG_HOME/yt/ytrc``) is deprecated.
+In order to perform an automatic migration of the old config, you are
+encouraged to run:
 
 .. code-block:: bash
 
    yt config migrate
 
-that will copy your current config file to the new location and store a backup
-copy as ``$HOME/.yt/config.bak``.
+This will convert your old config file to the toml format. The original file
+will be moved to ``$XDG_CONFIG_HOME/yt/ytrc.bak``.
 
 Examples
 ++++++++
@@ -364,23 +366,23 @@ Listing current content of the config file:
 
    $ yt config list
    [yt]
-   loglevel = 50
+   log_level = 50
 
 Obtaining a single config value by name:
 
 .. code-block:: bash
 
-   $ yt config get yt loglevel
+   $ yt config get yt log_level
    50
 
 Changing a single config value:
 
 .. code-block:: bash
 
-   $ yt config set yt loglevel 10
+   $ yt config set yt log_level 10
 
 Removing a single config entry:
 
 .. code-block:: bash
 
-   $ yt config rm yt loglevel
+   $ yt config rm yt log_level

doc/source/reference/configuration.rst

@@ -9,39 +9,63 @@ This customization is done through :ref:`configuration-file` and
 
 .. _configuration-file:
 
-The Configuration File
-----------------------
+The Configuration
+-----------------
 
-The configuration is a simple text file setting internal yt variables to
-custom default values to be used in future sessions.
+The configuration is stored in simple text files (in the `toml <https://github.com/toml-lang/toml>`_ format).
+The files allow to set internal yt variables to custom default values to be used in future sessions.
+The configuration can either be stored :ref:`globally<Global Configuration>` or :ref:`locally<Local Configuration>`.
 
-Configuration File Format
-^^^^^^^^^^^^^^^^^^^^^^^^^
+Global Configuration
+^^^^^^^^^^^^^^^^^^^^
 
-yt will look for and recognize the file ``$HOME/.config/yt/ytrc`` as a configuration
-file, containing several options that can be modified and adjusted to control
-runtime behavior.  For example, a sample ``$HOME/.config/yt/ytrc`` file could look
+If no local configuration file exists, yt will look for and recognize the file
+``$HOME/.config/yt/yt.toml`` as a configuration file, containing several options
+that can be modified and adjusted to control runtime behavior.  For example, a sample
+``$HOME/.config/yt/yt.toml`` file could look
 like:
 
 .. code-block:: none
 
    [yt]
-   loglevel = 1
-   maximumstoreddatasets = 10000
+   log_level = 1
+   maximum_stored_datasets = 10000
 
 This configuration file would set the logging threshold much lower, enabling
 much more voluminous output from yt.  Additionally, it increases the number of
 datasets tracked between instantiations of yt. The configuration file can be
-managed using the ``yt config`` helper. It can list, add, modify and remove
+managed using the ``yt config --global`` helper. It can list, add, modify and remove
 options from the configuration file, e.g.:
 
 .. code-block:: none
 
    $ yt config -h
    $ yt config list
-   $ yt config set yt loglevel 1
-   $ yt config rm yt maximumstoreddatasets
+   $ yt config set yt log_level 1
+   $ yt config rm yt maximum_stored_datasets
+
+
+Local Configuration
+^^^^^^^^^^^^^^^^^^^
+
+yt will look for a file named ``yt.toml`` in the current directory. If present, its options
+are loaded and the global configuration is not read. Local configuration files
+can contain the same options as the global one.
+
+Local configuration files can either be edited manually, or alternatively they
+can be managed using ``yt config --local``. It can list, add, modify and remove
+options, and display the path to the local configuration file, e.g.:
 
+.. code-block:: none
+
+   $ yt config -h
+   $ yt config list --local
+   $ yt config set --local yt log_level 1
+   $ yt config rm --local yt maximum_stored_datasets
+   $ yt config print-path --local
+
+If no local configuration file is present, these commands will create an (empty) one
+in the current working directory.
 
 Configuration Options At Runtime
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -68,7 +92,7 @@ Here is an example script, where we adjust the logging at startup:
    ds = yt.load("my_data0001")
    ds.print_stats()
 
-This has the same effect as setting ``loglevel = 1`` in the configuration
+This has the same effect as setting ``log_level = 1`` in the configuration
 file. Note that a log level of 1 means that all log messages are printed to
 stdout.  To disable logging, set the log level to 50.
 
@@ -79,13 +103,13 @@ Available Configuration Options
 The following external parameters are available.  A number of parameters are
 used internally.
 
-* ``coloredlogs`` (default: ``False``): Should logs be colored?
+* ``colored_logs`` (default: ``False``): Should logs be colored?
 * ``default_colormap`` (default: ``arbre``): What colormap should be used by
   default for yt-produced images?
-* ``pluginfilename``  (default ``my_plugins.py``) The name of our plugin file.
-* ``logfile`` (default: ``False``): Should we output to a log file in the
+* ``plugin_filename``  (default ``my_plugins.py``) The name of our plugin file.
+* ``log_file`` (default: ``False``): Should we output to a log file in the
   filesystem?
-* ``loglevel`` (default: ``20``): What is the threshold (0 to 50) for
+* ``log_level`` (default: ``20``): What is the threshold (0 to 50) for
   outputting log files?
 * ``test_data_dir`` (default: ``/does/not/exist``): The default path the
   ``load()`` function searches for datasets when it cannot find a dataset in the
@@ -108,9 +132,9 @@ used internally.
   :ref:`object serialization <object-serialization>`
 * ``sketchfab_api_key`` (default: empty): API key for https://sketchfab.com/ for
   uploading AMRSurface objects.
-* ``suppressStreamLogging`` (default: ``False``): If true, execution mode will be
+* ``suppress_stream_logging`` (default: ``False``): If true, execution mode will be
   quiet.
-* ``stdoutStreamLogging`` (default: ``False``): If true, logging is directed
+* ``stdout_stream_logging`` (default: ``False``): If true, logging is directed
   to stdout rather than stderr
 * ``skip_dataset_cache`` (default: ``False``): If true, automatic caching of datasets
   is turned off.
@@ -133,8 +157,8 @@ Global system plugin file
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 yt will look for and recognize the file ``$HOME/.config/yt/my_plugins.py`` as a
-plugin file. It is possible to rename this file to ``$HOME/.config/yt/<pluginfilename>.py``
-by defining ``pluginfilename`` in your ytrc file, as mentioned above.
+plugin file. It is possible to rename this file to ``$HOME/.config/yt/<plugin_filename>.py``
+by defining ``plugin_filename`` in your `yt.toml` file, as mentioned above.
 
 .. note::
 
@@ -143,6 +167,7 @@ by defining ``pluginfilename`` in your ytrc file, as mentioned above.
    command line entry points parse the plugin file, so the ``my_plugins.py``
    file will be parsed if you enter yt that way.
 
+
 Local project plugin file
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 

doc/source/visualizing/sketchfab.rst

@@ -104,7 +104,7 @@ The ``YTSurface`` object includes a method to upload directly to Sketchfab,
 but it requires that you get an API key first.  You can get this API key by
 creating an account and then going to your "dashboard," where it will be listed
 on the right hand side.  Once you've obtained it, put it into your
-``~/.config/yt/ytrc`` file under the heading ``[yt]`` as the variable
+``~/.config/yt/yt.toml`` file under the heading ``[yt]`` as the variable
 ``sketchfab_api_key``.  If you don't want to do this, you can also supply it as
 an argument to the function ``export_sketchfab``.
 

setup.py

@@ -147,6 +147,7 @@ def has_ext_modules(self):
             "unyt>=2.7.2",
             "more_itertools>=8.4",
             "tqdm>=3.4.0",
+            "toml>=0.10.2",
         ],
         extras_require={"hub": ["girder_client"], "mapserver": ["bottle"]},
         cmdclass={"sdist": sdist, "build_ext": build_ext},

tests/ci_install.sh

@@ -21,9 +21,9 @@ esac
 
 # Disable excessive output
 mkdir -p $HOME/.config/yt
-echo "[yt]" > $HOME/.config/yt/ytrc
-echo "suppressStreamLogging = True" >> $HOME/.config/yt/ytrc
-cat $HOME/.config/yt/ytrc
+echo "[yt]" > $HOME/.config/yt/yt.toml
+echo "suppress_stream_logging = true" >> $HOME/.config/yt/yt.toml
+cat $HOME/.config/yt/yt.toml
 # Sets default backend to Agg
 cp tests/matplotlibrc .
 

tests/test_requirements.txt

@@ -32,3 +32,4 @@ pykdtree~=1.3.1
 nose-exclude
 more_itertools>=8.4
 tqdm>=3.4.0
+toml>=0.10.2

yt/__init__.py

@@ -11,7 +11,7 @@
 
 if sys.version_info[0] < 3:
     raise Exception(
-        "Python 2 no longer supported.  Please install Python 3 for use with yt."
+        "Python 2 is no longer supported.  Please install Python 3 for use with yt."
     )
 
 __version__ = "4.0.dev0"
@@ -155,9 +155,9 @@ def _check_deprecated_parameters():
     from yt._maintenance.deprecation import issue_deprecation_warning
     from yt.config import ytcfg
 
-    if ytcfg.getboolean("yt", "loadfieldplugins"):
+    if ytcfg.get("yt", "load_field_plugins"):
         issue_deprecation_warning(
-            "Found deprecated parameter 'loadfieldplugins' parameter in yt rcfile.",
+            "Found deprecated parameter 'load_field_plugins' in yt's configuration file.",
             removal="4.1.0",
         )