♻️ Reimplementation of Shell

xtl.jobs.shells
- Reimplementation of xtl.automate.shells.Shell as frozen dataclass
  singleton instances
- New Shell enum for tabulating available shells, comparison and
  initialization directly from the members

docs/xtl.jobs.shells.rst
- API documentation for shells.py

Author: dtriand

docs/source/api/xtl.jobs.batchfiles.rst

@@ -0,0 +1,7 @@
+``xtl.jobs.batchfiles`` module
+==============================
+
+.. automodule:: xtl.jobs.batchfiles
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/xtl.jobs.rst

@@ -0,0 +1,19 @@
+``xtl.jobs`` package
+====================
+
+Module contents
+---------------
+
+.. automodule:: xtl.jobs
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 3
+
+   xtl.jobs.shells
+   xtl.jobs.batchfiles

docs/source/api/xtl.jobs.shells.rst

@@ -0,0 +1,48 @@
+``xtl.jobs.shells`` module
+==========================
+
+.. automodule:: xtl.jobs.shells
+   :no-members:
+
+Contents
+--------
+
+.. autoclass:: xtl.jobs.shells.Shell
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :exclude-members: __new__
+
+.. autoclass:: xtl.jobs.shells.BaseShell
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :exclude-members: __init__, __new__
+
+.. autoclass:: xtl.jobs.shells.BashShell
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :exclude-members: __init__
+
+.. autoclass:: xtl.jobs.shells.CmdShell
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :exclude-members: __init__
+
+.. autoclass:: xtl.jobs.shells.PowerShell
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :exclude-members: __init__
+
+.. autoclass:: xtl.jobs.shells.DefaultShell
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: xtl.jobs.shells.ShellType
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/xtl.rst

@@ -17,3 +17,4 @@ Subpackages
 
    xtl.common
    xtl.config
+   xtl.jobs

src/xtl/common/compatibility.py

@@ -27,9 +27,12 @@
 # TODO: Remove when dropping support for Python 3.13 (EOL: 10/2029)
 PY313_OR_LESS: bool = (PY_VERS < (3, 14))
 """Python version is 3.13 or less"""
+# Features missing in Python 3.13:
+# - Deferred evaluation of annotations (`from __future__ import annotations`)
 
 # TODO: Remove when dropping support for Python 3.14 (EOL: 10/2030)
 PY314_OR_LESS: bool = (PY_VERS < (3, 15))
+"""Python version is 3.14 or less"""
 
 #############
 # OS checks #

src/xtl/config/settings.py

@@ -262,18 +262,18 @@ def initialize(cls) -> 'XTLSettings':
         # Check settings version
         _v = version_from_str(_settings.version)
         if _v.tuple_safe < current_version.tuple_safe:
-            logger.warn('Using settings from an older version of XTL %(version)s.',
-                        {'version': _v.string})
+            logger.warning('Using settings from an older version of XTL %(version)s.',
+                           {'version': _v.string})
         elif _v.tuple_safe > current_version.tuple_safe:
-            logger.warn('Using settings from a newer version of XTL %(version)s. '
-                        'XTL might not behave as intended. Use at your own risk!',
-                        {'version': _v.string})
+            logger.warning('Using settings from a newer version of XTL %(version)s. '
+                           'XTL might not behave as intended. Use at your own risk!',
+                           {'version': _v.string})
 
         # Check for extra keys in the nested Options
         extra = _settings.__pydantic_extra__ or dict()
         extra.update(_get_extra_keys(_settings))
         if extra:
-            logger.warng('Found and ignored unknown keys in the config file',
-                         extra=extra)
+            logger.warning('Found and ignored unknown keys in the config file',
+                           extra=extra)
 
         return _settings

src/xtl/jobs/__init__.py

@@ -0,0 +1 @@
+from .shells import *