feat(move): add configuration option to change paths

Illegal characters will also be removed now from paths.

Author: jtpavlock

.pre-commit-config.yaml

@@ -1,31 +1,42 @@
 default_stages: [commit]
 
 repos:
-  - repo: https://github.com/psf/black
-    rev: 22.6.0
+  - repo: local
     hooks:
-      - id: black
-        language_version: python3
+    -   id: black
+        name: black
+        entry: black
+        language: system
+        types: [python]
 
-  - repo: https://gitlab.com/pycqa/flake8
-    rev: 3.9.2
+  - repo: local
     hooks:
-      - id: flake8
-        additional_dependencies:
-          [flake8-use-fstring, flake8-docstrings, wemake-python-styleguide]
+    -   id: flake8
+        name: flake8
+        entry: flake8
+        language: system
+        types: [python]
 
-  - repo: https://github.com/commitizen-tools/commitizen
-    rev: v2.31.0
+  - repo: local
     hooks:
-      - id: commitizen
+    -   id: commitizen
+        name: commitizen
+        entry: commitizen
+        language: system
         stages: [commit-msg]
 
-  - repo: https://github.com/timothycrosley/isort
-    rev: 5.10.1
+  - repo: local
     hooks:
-      - id: isort
+    -   id: isort
+        name: isort
+        entry: isort
+        language: system
+        types: [python]
 
-  - repo: https://github.com/RobertCraigie/pyright-python
-    rev: v1.1.267
+  - repo: local
     hooks:
-    - id: pyright
+    -   id: pyright
+        name: pyright
+        entry: pyright
+        language: system
+        types: [python]

docs/developers/api/core.rst

@@ -10,6 +10,7 @@ Config
    :members:
    :exclude-members: plugin, name
 
+.. _Library API:
 
 Library
 =======

docs/fields.rst

@@ -1,3 +1,5 @@
+.. _Fields:
+
 ######
 Fields
 ######
@@ -30,6 +32,8 @@ Track Fields
     "track_num", "Track number", ""
     "year", "Album release year", ""
 
+.. _Album Fields:
+
 ************
 Album Fields
 ************
@@ -45,11 +49,14 @@ Album Fields
     "title", "Album title", ""
     "year", "Album release year", ""
 
+.. _Extra Fields:
+
 ************
 Extra Fields
 ************
 .. csv-table::
     :header: "Field", "Description", "Notes"
     :widths: 20, 50, 50
 
+    "filename", "The filename of the extra.", ""
     "path", "Filesystem path of the extra", ""

docs/plugins/move.rst

@@ -1,20 +1,12 @@
+.. _Move Plugin:
+
 ####
 Move
 ####
 Alters the location of files in your library.
 
-The ``move`` plugin provides the following features:
-
-* Any items added to your library will be copied to the location set by the global option, ``library_path`` in your configuration file.
-* Any items moved or copied will have their paths set to a default format. This default format cannot currently be configured, and is as follows:
-
-  * Albums: ``{library_path}/{albumartist}/{album_title} ({album_year})/``
-  * Tracks: ``{album_path}/{track_number} - {track_title}.{file_ext}``
-
-    If the album contains more than one disc, tracks will be formatted as:
-
-    ``{album_path}/Disc {disc#}/{track_number} - {track_title}.{file_ext}``
-  * Extras: ``{album_path}/{original_file_name}``
+.. note::
+    Any items added to your library will be automatically copied to their respective path configurations.
 
 *************
 Configuration
@@ -26,10 +18,35 @@ The ``move`` plugin is enabled by default and provides the following configurati
 
     If ``true``, non-ascii characters will be converted to their ascii equivalents, e.g. ``café.mp3`` will become ``cafe.mp3``.
 
+Path Configuration Options
+--------------------------
+``album_path = "{album.artist}/{album.title} ({album.year})"``
+    Album filesystem path format relative to the global configuration option, :ref:`library_path <library_path config option>`.
+
+
+``track_path = "{f'Disc {track.disc:02}' if track.disc_total > 1 else ''}/{track.track_num:02} - {track.title}{track.path.suffix}"``
+    Track filesystem path format relative to ``album_path``.
+
+    .. note::
+        - The ``if`` statement inside the path simply means that if there is more than one disc in the album, the tracks will be put into separate directories for their respective disc.
+        - Include ``track.path.suffix`` at the end if you wish to retain the file extension of the track file.
+
+``extra_path = "{extra.filename}"``
+    Extra filesystem path format relative to ``album_path``.
+
+Paths are formatted using python `f-strings <https://docs.python.org/3/tutorial/inputoutput.html#formatted-string-literals>`_ which, as demonstrated by the default track path, allow all the advanced formatting and expression evaluation that come with them. You can access any of the :ref:`respective item's fields <Fields>` in these strings using ``{[album/track/extra].field}`` notation as shown.
+
+.. important::
+    Windows users should use a forward slash ``/`` when delineating sub-directories in path formats as the back slash ``\`` is used as an escape character.
+
+.. tip::
+    - For any path formatting changes, run ``moe move -n`` for a dry-run to avoid any unexpected results.
+    - For a more detailed look at all the field options and types, you take a look at the :ref:`library api <Library API>`. ``album``, ``track``, and ``extra`` in the path formats are ``Album``, ``Track``, and ``Extra`` objects respectively and thus you can reference any of their available attributes.
+
 ***********
 Commandline
 ***********
-The ``move`` command will move all items in the library according to your configuration file. This is useful if you make changes to the configuration file, and you'd like to move the items in your library to reflect the new changes.
+The ``move`` command will move all items in the library according to your configuration file. This can be used to update the items in your library to reflect changes in your configuration.
 
 .. code-block:: bash
 

moe/plugins/move/move_core.py

@@ -1,6 +1,7 @@
 """Core api for moving items."""
 
 import logging
+import re
 import shutil
 from contextlib import suppress
 from pathlib import Path
@@ -24,8 +25,24 @@
 @moe.hookimpl
 def add_config_validator(settings: dynaconf.base.LazySettings):
     """Validate move plugin configuration settings."""
+    default_album_path = "{album.artist}/{album.title} ({album.year})"
+    default_extra_path = "{extra.filename}"
+    default_track_path = (
+        "{f'Disc {track.disc:02}' if track.disc_total > 1 else ''}/"
+        "{track.track_num:02} - {track.title}{track.path.suffix}"
+    )
+
+    settings.validators.register(
+        dynaconf.Validator("MOVE.ASCIIFY_PATHS", default=False)
+    )
+    settings.validators.register(
+        dynaconf.Validator("MOVE.ALBUM_PATH", default=default_album_path)
+    )
     settings.validators.register(
-        dynaconf.Validator("MOVE.ASCIIFY_PATHS", must_exist=True, default=False)
+        dynaconf.Validator("MOVE.EXTRA_PATH", default=default_extra_path)
+    )
+    settings.validators.register(
+        dynaconf.Validator("MOVE.TRACK_PATH", default=default_track_path)
     )
 
 
@@ -88,14 +105,17 @@ def _fmt_album_path(config: Config, album: Album) -> Path:
         Formatted album directory under the config ``library_path``.
     """
     library_path = Path(config.settings.library_path).expanduser()
-    album_dir_name = f"{album.artist}/{album.title} ({album.year})"
+    album_path = _eval_path_template(config.settings.move.album_path, album)
 
-    return library_path / album_dir_name
+    return library_path / album_path
 
 
 def _fmt_extra_path(config: Config, extra: Extra) -> Path:
     """Returns a formatted extra path according to the user configuration."""
-    return _fmt_album_path(config, extra.album_obj) / extra.path.name
+    album_path = _fmt_album_path(config, extra.album_obj)
+    extra_path = _eval_path_template(config.settings.move.extra_path, extra)
+
+    return album_path / extra_path
 
 
 def _fmt_track_path(config: Config, track: Track) -> Path:
@@ -111,14 +131,97 @@ def _fmt_track_path(config: Config, track: Track) -> Path:
     Returns:
         Formatted track path under its album path.
     """
-    disc_dir_name = ""
-    if track.disc_total > 1:
-        disc_dir_name = f"Disc {track.disc:02}"
-    disc_dir = _fmt_album_path(config, track.album_obj) / disc_dir_name
+    album_path = _fmt_album_path(config, track.album_obj)
+    track_path = _eval_path_template(config.settings.move.track_path, track)
+
+    return album_path / track_path
+
+
+def _eval_path_template(template, lib_item) -> str:
+    """Evaluates and sanitizes a path template.
+
+    Args:
+        template: Path template.
+            See `_lazy_fstr_item()` for more info on accepted f-string templates.
+        lib_item: Library item associated with the template.
+
+    Returns:
+        Evaluated path.
+
+    Raises:
+        NotImplementedError: You discovered a new library item!
+    """
+    template_parts = template.split("/")
+    sanitized_parts = []
+    for template_part in template_parts:
+        path_part = _lazy_fstr_item(template_part, lib_item)
+        sanitized_part = _sanitize_path_part(path_part)
+        if sanitized_part:
+            sanitized_parts.append(sanitized_part)
+
+    return "/".join(sanitized_parts)
+
+
+def _lazy_fstr_item(template: str, lib_item: LibItem) -> str:
+    """Evalutes the given f-string template for a specific library item.
+
+    Args:
+        template: f-string template to evaluate.
+            All library items should have their own template and refer to variables as:
+                Album: album (e.g. {album.title}, {album.artist})
+                Track: track (e.g. {track.title}, {track.artist})
+                Extra: extra (e.g. {extra.filename}
+        lib_item: Library item referenced in the template.
+
+
+    Example:
+        The default path template for an album is::
+
+            {album.artist}/{album.title} ({album.year})
+
+    Returns:
+        Evaluated f-string.
+
+    Raises:
+        NotImplementedError: You discovered a new library item!
+    """
+    # add the appropriate library item to the scope
+    if isinstance(lib_item, Album):
+        album = lib_item  # noqa: F841
+    elif isinstance(lib_item, Track):
+        track = lib_item  # noqa: F841
+    elif isinstance(lib_item, Extra):
+        extra = lib_item  # noqa: F841
+    else:
+        raise NotImplementedError
+
+    return eval(f'f"""{template}"""')
+
+
+def _sanitize_path_part(path_part: str) -> str:
+    """Sanitizes a part of a path to be compatible with most filesystems.
+
+    Note:
+        Only sub-paths of the library path will be affected.
+
+    Args:
+        path_part: Path part to sanitize. Must be a single 'part' of a path, i.e. no /
+            separators.
+
+    Returns:
+        Path part with all the replacements applied.
+    """
+    PATH_REPLACE_CHARS = {
+        r"^\.": "_",  # leading '.' (hidden files on Unix)
+        r'[<>:"\?\*\|\\/]': "_",  # <, >, : , ", ?, *, |, \, / (Windows reserved chars)
+        r"\.$": "_",  # trailing '.' (Windows restriction)
+        r"\s+$": "",  # trailing whitespace (Windows restriction)
+    }
 
-    track_filename = f"{track.track_num:02} - {track.title}{track.path.suffix}"
+    for regex, replacement in PATH_REPLACE_CHARS.items():
+        path_part = re.sub(regex, replacement, path_part)
 
-    return disc_dir / track_filename
+    return path_part
 
 
 ########################################################################################

tests/plugins/move/test_move_core.py

@@ -23,6 +23,37 @@ def mock_copy():
 ########################################################################################
 # Test format paths
 ########################################################################################
+class TestReplaceChars:
+    """Test replacing of illegal or unwanted characters in paths."""
+
+    def test_replace_chars(self, mock_track_factory, tmp_config):
+        """Replace all the defined illegal characters from any paths."""
+        config = tmp_config(
+            settings="""
+            default_plugins = ["move"]
+            [move]
+            track_path = "{track.title}"
+            """
+        )
+        tracks = []
+        replacements = []
+        tracks.append(mock_track_factory(title='/ reserved <, >, :, ", ?, *, |, /'))
+        replacements.append("_ reserved _, _, _, _, _, _, _, _")
+        tracks.append(mock_track_factory(title=".leading dot"))
+        replacements.append("_leading dot")
+        tracks.append(mock_track_factory(title="trailing dot."))
+        replacements.append("trailing dot_")
+        tracks.append(mock_track_factory(title="trailing whitespace "))
+        replacements.append("trailing whitespace")
+
+        formatted_paths = []
+        for track in tracks:
+            formatted_paths.append(moe_move.fmt_item_path(config, track))
+
+        for path in formatted_paths:
+            assert any(replacement == path.name for replacement in replacements)
+
+
 class TestFmtAlbumPath:
     """Tests `fmt_item_path(album)`."""
 
@@ -353,6 +384,18 @@ def test_asciify_paths(self, tmp_move_config):
         """`asciify_paths` is not required and defaults to 'False'."""
         assert tmp_move_config.settings.move.asciify_paths == False  # noqa: E712
 
+    def test_album_path(self, tmp_move_config):
+        """`album_path` is not required and has a default."""
+        assert tmp_move_config.settings.move.album_path
+
+    def test_extra_path(self, tmp_move_config):
+        """`extra_path` is not required and has a default."""
+        assert tmp_move_config.settings.move.extra_path
+
+    def test_track_path(self, tmp_move_config):
+        """`track_path` is not required and has a default."""
+        assert tmp_move_config.settings.move.track_path
+
 
 class TestPostAdd:
     """Test the `post_add` hook implementation.