Merge branch 'master' into auto_formatters

.github/workflows/ci.yaml

@@ -12,7 +12,7 @@ jobs:
     strategy:
       matrix:
         platform: [ubuntu-latest, windows-latest]
-        python-version: ['3.7', '3.8', '3.9', '3.10', '3.11-dev']
+        python-version: ['3.7', '3.8', '3.9', '3.x', '3.12-dev']
 
     env:
       PY_COLORS: 1
@@ -45,17 +45,17 @@ jobs:
           sudo apt install ffmpeg  # For replaygain
 
       - name: Test older Python versions with tox
-        if: matrix.python-version != '3.10' && matrix.python-version != '3.11-dev'
+        if: matrix.python-version != '3.x' && matrix.python-version != '3.12-dev'
         run: |
           tox -e py-test
 
       - name: Test latest Python version with tox and get coverage
-        if: matrix.python-version == '3.10'
+        if: matrix.python-version == '3.x'
         run: |
           tox -vv -e py-cov
 
       - name: Test latest Python version with tox and mypy
-        if: matrix.python-version == '3.10'
+        if: matrix.python-version == '3.x'
         # continue-on-error is not ideal since it doesn't give a visible
         # warning, but there doesn't seem to be anything better:
         # https://github.com/actions/toolkit/issues/399
@@ -64,7 +64,7 @@ jobs:
           tox -vv -e py-mypy
 
       - name: Test nightly Python version with tox
-        if: matrix.python-version == '3.11-dev'
+        if: matrix.python-version == '3.12-dev'
         # continue-on-error is not ideal since it doesn't give a visible
         # warning, but there doesn't seem to be anything better:
         # https://github.com/actions/toolkit/issues/399
@@ -73,7 +73,7 @@ jobs:
           tox -e py-test
 
       - name: Upload code coverage
-        if: matrix.python-version == '3.10'
+        if: matrix.python-version == '3.x'
         run: |
           pip install codecov || true
           codecov || true
@@ -87,10 +87,10 @@ jobs:
     steps:
       - uses: actions/checkout@v2
 
-      - name: Set up Python 3.10
+      - name: Set up Python 3.x
         uses: actions/setup-python@v2
         with:
-          python-version: '3.10'
+          python-version: '3.x'
 
       - name: Install base dependencies
         run: |
@@ -109,10 +109,10 @@ jobs:
     steps:
       - uses: actions/checkout@v2
 
-      - name: Set up Python 3.10
+      - name: Set up Python 3.x
         uses: actions/setup-python@v2
         with:
-          python-version: '3.10'
+          python-version: '3.x'
 
       - name: Install base dependencies
         run: |

.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

CONTRIBUTING.rst

@@ -237,7 +237,7 @@ guidelines to follow:
 -  If you have a Unicode path or you’re not sure whether something is
    Unicode or not, pass it through ``bytestring_path`` function in the
    ``beets.util`` module to convert it to bytes.
--  Pass every path name trough the ``syspath`` function (also in
+-  Pass every path name through the ``syspath`` function (also in
    ``beets.util``) before sending it to any *operating system* file
    operation (``open``, for example). This is necessary to use long
    filenames (which, maddeningly, must be Unicode) on Windows. This
@@ -288,7 +288,7 @@ Other ways to run the tests:
 You can also see the latest test results on `Linux`_ and on `Windows`_.
 
 Note, if you are on Windows and are seeing errors running tox, it may be related to `this issue`_,
-in which case you may have to install tox v3.8.3 e.g. ``python -m pip install tox=3.8.3``
+in which case you may have to install tox v3.8.3 e.g. ``python -m pip install tox==3.8.3``
 
 .. _this issue: https://github.com/tox-dev/tox/issues/1550
 
@@ -347,7 +347,6 @@ others. See `unittest.mock`_ for more info.
    ``mock.patch``, as they require manual cleanup. Use the annotation or
    context manager forms instead.
 
-.. _Python unittest: https://docs.python.org/2/library/unittest.html
 .. _Codecov: https://codecov.io/github/beetbox/beets
 .. _pytest-random: https://github.com/klrmn/pytest-random
 .. _tox: https://tox.readthedocs.io/en/latest/
@@ -358,10 +357,9 @@ others. See `unittest.mock`_ for more info.
 .. _`https://github.com/beetbox/beets/blob/master/setup.py#L99`: https://github.com/beetbox/beets/blob/master/setup.py#L99
 .. _test: https://github.com/beetbox/beets/tree/master/test
 .. _`https://github.com/beetbox/beets/blob/master/test/test_template.py#L224`: https://github.com/beetbox/beets/blob/master/test/test_template.py#L224
-.. _unittest: https://docs.python.org/3.8/library/unittest.html
+.. _unittest: https://docs.python.org/3/library/unittest.html
 .. _integration test: https://github.com/beetbox/beets/actions?query=workflow%3A%22integration+tests%22
 .. _unittest.mock: https://docs.python.org/3/library/unittest.mock.html
-.. _Python unittest: https://docs.python.org/2/library/unittest.html
 .. _documentation: https://beets.readthedocs.io/en/stable/
 .. _pip: https://pip.pypa.io/en/stable/
 .. _vim: https://www.vim.org/

README.rst

@@ -80,10 +80,11 @@ shockingly simple if you know a little Python.
 Install
 -------
 
-You can install beets by typing ``pip install beets``.
+You can install beets by typing ``pip install beets`` or directly from Github (see details `here`_).
 Beets has also been packaged in the `software repositories`_ of several
 distributions. Check out the `Getting Started`_ guide for more information.
 
+.. _here: https://beets.readthedocs.io/en/latest/faq.html#run-the-latest-source-version-of-beets
 .. _Getting Started: https://beets.readthedocs.org/page/guides/main.html
 .. _software repositories: https://repology.org/project/beets/versions
 

beets/autotag/__init__.py

@@ -14,7 +14,9 @@
 
 """Facilities for automatically determining files' correct metadata.
 """
+from typing import Mapping
 
+from beets.library import Item
 
 from beets import logging
 from beets import config
@@ -39,28 +41,36 @@
         'va',
         'releasegroup_id',
         'artist_id',
+        'artists_ids',
         'album_id',
         'mediums',
         'tracks',
         'year',
         'month',
         'day',
         'artist',
+        'artists',
         'artist_credit',
+        'artists_credit',
         'artist_sort',
+        'artists_sort',
         'data_url'
     ),
     'track': (
         'track_alt',
         'artist_id',
+        'artists_ids',
         'release_track_id',
         'medium',
         'index',
         'medium_index',
         'title',
         'artist_credit',
+        'artists_credit',
         'artist_sort',
+        'artists_sort',
         'artist',
+        'artists',
         'track_id',
         'medium_total',
         'data_url',
@@ -71,17 +81,22 @@
 
 # Additional utilities for the main interface.
 
-def apply_item_metadata(item, track_info):
+def apply_item_metadata(item: Item, track_info: TrackInfo):
     """Set an item's metadata from its matched TrackInfo object.
     """
     item.artist = track_info.artist
+    item.artists = track_info.artists
     item.artist_sort = track_info.artist_sort
+    item.artists_sort = track_info.artists_sort
     item.artist_credit = track_info.artist_credit
+    item.artists_credit = track_info.artists_credit
     item.title = track_info.title
     item.mb_trackid = track_info.track_id
     item.mb_releasetrackid = track_info.release_track_id
     if track_info.artist_id:
         item.mb_artistid = track_info.artist_id
+    if track_info.artists_ids:
+        item.mb_artistids = track_info.artists_ids
 
     for field, value in track_info.items():
         # We only overwrite fields that are not already hardcoded.
@@ -95,7 +110,7 @@ def apply_item_metadata(item, track_info):
     # and track number). Perhaps these should be emptied?
 
 
-def apply_metadata(album_info, mapping):
+def apply_metadata(album_info: AlbumInfo, mapping: Mapping[Item, TrackInfo]):
     """Set the items' metadata to match an AlbumInfo object using a
     mapping from Items to TrackInfo objects.
     """
@@ -106,21 +121,34 @@ def apply_metadata(album_info, mapping):
                            track_info.artist or
                            album_info.artist_credit or
                            album_info.artist)
+            item.artists = (track_info.artists_credit or
+                            track_info.artists or
+                            album_info.artists_credit or
+                            album_info.artists)
             item.albumartist = (album_info.artist_credit or
                                 album_info.artist)
+            item.albumartists = (album_info.artists_credit or
+                                 album_info.artists)
         else:
             item.artist = (track_info.artist or album_info.artist)
+            item.artists = (track_info.artists or album_info.artists)
             item.albumartist = album_info.artist
+            item.albumartists = album_info.artists
 
         # Album.
         item.album = album_info.album
 
         # Artist sort and credit names.
         item.artist_sort = track_info.artist_sort or album_info.artist_sort
+        item.artists_sort = track_info.artists_sort or album_info.artists_sort
         item.artist_credit = (track_info.artist_credit or
                               album_info.artist_credit)
+        item.artists_credit = (track_info.artists_credit or
+                               album_info.artists_credit)
         item.albumartist_sort = album_info.artist_sort
+        item.albumartists_sort = album_info.artists_sort
         item.albumartist_credit = album_info.artist_credit
+        item.albumartists_credit = album_info.artists_credit
 
         # Release date.
         for prefix in '', 'original_':
@@ -172,7 +200,14 @@ def apply_metadata(album_info, mapping):
             item.mb_artistid = track_info.artist_id
         else:
             item.mb_artistid = album_info.artist_id
+
+        if track_info.artists_ids:
+            item.mb_artistids = track_info.artists_ids
+        else:
+            item.mb_artistids = album_info.artists_ids
+
         item.mb_albumartistid = album_info.artist_id
+        item.mb_albumartistids = album_info.artists_ids
         item.mb_releasegroupid = album_info.releasegroup_id
 
         # Compilation flag.