Merge pull request #59 from cjcodeproj/integration

Integration to Main (0.1.7)

Author: cjcodeproj

CHANGELOG.md

@@ -1,6 +1,17 @@
 musicscan CHANGELOG
 ======================
 
+## RELEASE 0.1.7
+ - [musicscan-57](https://github.com/cjcodeproj/musicscan/issues/57) Release 0.1.7
+ - [musicscan-36](https://github.com/cjcodeproj/musicscan/issues/36) Update some editing notes
+ - [musicscan-52](https://github.com/cjcodeproj/musicscan/issues/52) Add new flags to RST documentation
+ - [musicscan-40](https://github.com/cjcodeproj/musicscan/issues/40) Documentation: flags option flag
+ - [musicscan-53](https://github.com/cjcodeproj/musicscan/issues/53) Album title is not sanitized
+ - [musicscan-51](https://github.com/cjcodeproj/musicscan/issues/51) Edit flag for Intro and Reprise
+ - [musicscan-22](https://github.com/cjcodeproj/musicscan/issues/22) Flag codes should probably be distinct between album and song
+ - [musicscan-49](https://github.com/cjcodeproj/musicscan/issues/49) id3scan should be a bin tool
+
+
 ## RELEASE 0.1.5
  - [musicscan-46](https://github.com/cjcodeproj/musicscan/issues/46) Release 0.1.5
  - [musicscan-34](https://github.com/cjcodeproj/musicscan/issues/34) Flag for bonus tracks

README.md

@@ -6,6 +6,18 @@ music collection and builds a set of XML files adhering to the vtmedia schema.
 It includes a tool that will recursively scan a directory for audio files
 containing ID3 tags and uses that data as the basis for bulding XML files.
 
+
+ * [How It Works](#how-it-works)
+ * [XML Schema](#xml-schema)
+ * [Scanning Example](#scanning-example)
+     * [The Audio CD File](#the-audio-cd-file)
+     * [The Index File](#the-index-file)
+     * [The Album File](#the-album-file)
+ * [Documentation](#documentation)
+ * [Building And Installing From Source Code](#building-and-installing-from-source-code)
+ * [Package Distribution](#package-distribution)
+
+
 ## How It Works
 
 It works under the assumption that the digital library was created by importing CDs
@@ -52,10 +64,11 @@ $ ls -1 "~/Music/iTunes/iTunes Media/Music/Garth Brooks/No Fences/"
 10 Wolves.m4a
 ```
 
-The `id3scan` tool will search that directory and create three files.
+The `id3scan` tool will search that directory and create three files.  Make sure the install path for the id3scan tool
+matches your environment command path.
 
 ```
-$ python3 -m musicscan.tools.id3scan --musicpath "~/Music/iTunes/iTunes Media/Music/Garth Brooks/No Fences" --write --outdir ~/tmp --split-xml
+$ id3scan --musicpath "~/Music/iTunes/iTunes Media/Music/Garth Brooks/No Fences" --write --outdir ~/tmp --split-xml
 ```
 
 ```

doc/id3scan.rst

@@ -5,14 +5,14 @@ musisscan.tools.id3scan
 NAME
 ----
 
-musicscan.tools.id3scan - scan files for ID3 metadata to build XML structures
+id3scan - scan files for ID3 metadata to build XML structures
 
 SYNOPSIS
 --------
 
 ::
 
-  python -m musicscan.tools.id3scan [-h] [--musicpath PATH]
+  id3scan [-h] [--musicpath PATH]
          [--outdir PATH]
          [--write/--no-write]
          [--split-xml/--no-split-xml]
@@ -48,7 +48,7 @@ OPTIONS
     If existing XML files are already in the output path, they will be overwritten.
 
 ``--flags``
-    If specified, additional XML comments will be embedded in the file containing
+    By default, additional XML comments will be embedded in the file containing context
     hints about the data, such as whether a song has a featured guest artist,
     or if a track is just filler material from the source CD.
 
@@ -77,8 +77,8 @@ correctly identify multiple artists, or distinguish between an individual artist
 If you don't like the results of your editing, it's possible to just delete the data
 and re-generate it by running the id3scan again.
 
-FLAGS
------
+ALBUM FLAGS
+-----------
 
 Flags are embedded information in the XML comments that provide information on
 how the software has interpreted the metadata
@@ -92,9 +92,19 @@ how the software has interpreted the metadata
 ``possible_soundtrack``
     The album is possibly a soundtrack from a film, television show, or play.
 
-``possible_score```
+``possible_score``
     The album is possible a musical score from a film, television show, or play.
 
+``possible_tribute``
+  The album is possibly a tribute to another musical artist.
+
+``possible_intro_and_reprise``
+  The first track of the album may be an introduction, and the final track may
+  be a repreise.
+
+TRACK FLAGS
+-----------
+
 ``detected_square_brackets``
     Square brackets were detected in the title of the track, suggesting extra
     metadata could be embedded in the title.
@@ -122,12 +132,27 @@ how the software has interpreted the metadata
 ``possible_blank_track``
     The track is possibly a blank track that contains no actual music.
 
+``possible_bonus_track``
+    It's possible the track is a bonus track, which could appear
+    on a re-issue of a CD or record.
+
 ``country_and_folk_genre_is_too_vague``
     The metadata genre value for the track is "Country & Folk", which
     actually is two different genres.  The value should be changed to
     the more accurate value.
 
+``missing_copyright_year``
+    The copyright year information could be missing.
+
+``missing_artist``
+    The artist name is missing
+
+``possible_intro_track``
+   The track could serve as an introduction to the album, or
+   to another track.
 
+``possible_reprise_track``
+    The track could serve as a reprise to the album.
 
 ENVIRONMENT VARIABLES
 ---------------------

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "musicscan"
-version = "0.1.5"
+version = "0.1.7"
 description = "Package for converting music metadata to XML"
 readme = "README.md"
 requires-python = ">3.8"
@@ -33,6 +33,8 @@ homepage = "https://github.com/cjcodeproj/musicscan"
 repository = "https://github.com/cjcodeproj/musicscan"
 changelog = "https://github.com/cjcodeproj/musicscan/blob/main/CHANGELOG.md"
 
+[project.scripts]
+id3scan = "musicscan.tools.id3scan:main_cli"
 
 [tools.setuptools]
 license-files = ["LICENSE"]

src/musicscan/data/analyzer.py

@@ -26,9 +26,11 @@
 Testing code to identify possible edit flags.
 '''
 
+# pylint: disable=too-many-public-methods
+
 import re
 from musicscan.data.cd import Album
-from musicscan.data.flags import FlagCodes
+from musicscan.data.flags import AlbumFlagCodes, TrackFlagCodes
 from musicscan.data.track import Track
 
 
@@ -42,11 +44,25 @@ def main_test(self, in_album: Album):
         '''
         Main album testing routine.
         '''
+        self.album_tests(in_album)
+        self.track_tests(in_album)
+        self.album_closing_tests(in_album)
+
+    def album_tests(self, in_album: Album):
+        '''
+        Perform tests against the album.
+        '''
         self.check_album_values(in_album)
         self.test_album_title(in_album)
         self.test_album_artist(in_album)
         self.test_soundtrack(in_album)
         self.test_score(in_album)
+        self.test_tribute(in_album)
+
+    def track_tests(self, in_album: Album):
+        '''
+        Perform tests against every track.
+        '''
         for dsc in sorted(in_album.discs):
             for trk in sorted(in_album.discs[dsc].tracks,
                               key=lambda x: x.track_no):
@@ -57,6 +73,15 @@ def main_test(self, in_album: Album):
                 self.test_track_genre(trk)
                 self.test_album_track_blank(trk)
                 self.test_album_track_bonus(trk)
+                self.test_album_track_intro(trk)
+                self.test_album_track_reprise(trk)
+
+    def album_closing_tests(self, in_album: Album):
+        '''
+        Perform additional tests after all
+        tracks are analzed.
+        '''
+        self.test_intro_reprise_presence(in_album)
 
     def check_album_values(self, in_album: Album):
         '''
@@ -65,7 +90,7 @@ def check_album_values(self, in_album: Album):
         '''
         if not in_album.title:
             in_album.title = 'PLACEHOLDER ALBUM TITLE'
-            in_album.flags.add_flag(FlagCodes.m_album_title)
+            in_album.flags.add_flag(TrackFlagCodes.m_album_title)
 
     def check_track_values(self, in_track: Track):
         '''
@@ -74,7 +99,7 @@ def check_track_values(self, in_track: Track):
         '''
         if not in_track.artist:
             in_track.artist = 'PLACEHOLDER TRACK ARTIST'
-            in_track.flags.add_flag(FlagCodes.m_track_artist)
+            in_track.flags.add_flag(TrackFlagCodes.m_track_artist)
 
     def test_album_title(self, in_album: Album):
         '''
@@ -84,9 +109,9 @@ def test_album_title(self, in_album: Album):
         greatest_p = re.compile(r'Greatest', re.IGNORECASE)
         hits_p = re.compile(r'\s+Hit', re.IGNORECASE)
         if greatest_p.search(in_album.title):
-            in_album.flags.add_flag(FlagCodes.p_greatest)
+            in_album.flags.add_flag(AlbumFlagCodes.p_greatest)
         if hits_p.search(in_album.title):
-            in_album.flags.add_flag(FlagCodes.p_hits_compo)
+            in_album.flags.add_flag(AlbumFlagCodes.p_hits_compo)
 
     def test_soundtrack(self, in_album: Album):
         '''
@@ -96,10 +121,10 @@ def test_soundtrack(self, in_album: Album):
         first_track = in_album.first_track()
         soundtrack_p = re.compile(r'\s+Soundtrack\s+', re.IGNORECASE)
         if soundtrack_p.search(in_album.title):
-            in_album.flags.add_flag(FlagCodes.p_soundtrack)
+            in_album.flags.add_flag(AlbumFlagCodes.p_soundtrack)
         if first_track.genre == 'Soundtrack':
-            if FlagCodes.p_soundtrack not in in_album.flags.flags:
-                in_album.flags.add_flag(FlagCodes.p_soundtrack)
+            if AlbumFlagCodes.p_soundtrack not in in_album.flags.flags:
+                in_album.flags.add_flag(AlbumFlagCodes.p_soundtrack)
 
     def test_score(self, in_album: Album):
         '''
@@ -108,7 +133,16 @@ def test_score(self, in_album: Album):
         '''
         score_p = re.compile(r'\s+Score\s+', re.IGNORECASE)
         if score_p.search(in_album.title):
-            in_album.flags.add_flag(FlagCodes.p_score)
+            in_album.flags.add_flag(AlbumFlagCodes.p_score)
+
+    def test_tribute(self, in_album: Album):
+        '''
+        Test if the album title suggests that it is a
+        tribute to another artist.
+        '''
+        tribute_p = re.compile(r'\s+Tribute\s+', re.IGNORECASE)
+        if tribute_p.search(in_album.title):
+            in_album.flags.add_flag(AlbumFlagCodes.p_tribute)
 
     def test_album_artist(self, in_album: Album):
         '''
@@ -117,17 +151,17 @@ def test_album_artist(self, in_album: Album):
         '''
         and_p = re.compile(r'\s+and\s+', re.IGNORECASE)
         if and_p.search(str(in_album.artist)):
-            in_album.flags.add_flag(FlagCodes.l_group)
+            in_album.flags.add_flag(TrackFlagCodes.l_group)
 
     def test_album_track_chrs(self, in_track: Track):
         '''
         Test the track title to indicate metadata may
         have been embeded in the track name in parenthesis.
         '''
         if '[' in in_track.title or ']' in in_track.title:
-            in_track.flags.add_flag(FlagCodes.d_sq_brackets)
+            in_track.flags.add_flag(TrackFlagCodes.d_sq_brackets)
         if '(' in in_track.title or ')' in in_track.title:
-            in_track.flags.add_flag(FlagCodes.d_parenthesis)
+            in_track.flags.add_flag(TrackFlagCodes.d_parenthesis)
 
     def test_album_track_featured(self, in_track: Track):
         '''
@@ -137,9 +171,9 @@ def test_album_track_featured(self, in_track: Track):
         feature_p = re.compile(r'Feat', re.IGNORECASE)
         with_p = re.compile(r'With\s+', re.IGNORECASE)
         if feature_p.search(in_track.title) or with_p.search(in_track.title):
-            in_track.flags.add_flag(FlagCodes.p_feat_artist)
+            in_track.flags.add_flag(TrackFlagCodes.p_feat_artist)
         if feature_p.search(in_track.artist) or with_p.search(in_track.artist):
-            in_track.flags.add_flag(FlagCodes.p_feat_artist)
+            in_track.flags.add_flag(TrackFlagCodes.p_feat_artist)
 
     def test_album_track_live(self, in_track: Track):
         '''
@@ -148,7 +182,7 @@ def test_album_track_live(self, in_track: Track):
         '''
         live_p = re.compile(r'Live\s+', re.IGNORECASE)
         if live_p.search(in_track.title):
-            in_track.flags.add_flag(FlagCodes.p_live)
+            in_track.flags.add_flag(TrackFlagCodes.p_live)
 
     def test_track_genre(self, in_track: Track):
         '''
@@ -157,7 +191,7 @@ def test_track_genre(self, in_track: Track):
         country_p = re.compile(r'Country & Folk', re.IGNORECASE)
         if in_track.genre:
             if country_p.search(in_track.genre):
-                in_track.flags.add_flag(FlagCodes.p_genre_country_folk)
+                in_track.flags.add_flag(TrackFlagCodes.p_genre_country_folk)
 
     def test_album_track_demo(self, in_track: Track):
         '''
@@ -166,7 +200,7 @@ def test_album_track_demo(self, in_track: Track):
         '''
         demo_p = re.compile(r'Demo', re.IGNORECASE)
         if demo_p.search(in_track.title):
-            in_track.flags.add_flag(FlagCodes.p_demo)
+            in_track.flags.add_flag(TrackFlagCodes.p_demo)
 
     def test_album_track_blank(self, in_track: Track):
         '''
@@ -175,7 +209,7 @@ def test_album_track_blank(self, in_track: Track):
         '''
         blank_p = re.compile(r'Blank', re.IGNORECASE)
         if blank_p.search(in_track.title):
-            in_track.flags.add_flag(FlagCodes.p_blank_track)
+            in_track.flags.add_flag(TrackFlagCodes.p_blank_track)
 
     def test_album_track_bonus(self, in_track: Track):
         '''
@@ -185,4 +219,42 @@ def test_album_track_bonus(self, in_track: Track):
         '''
         bonus_p = re.compile(r'\W+Bonus', re.IGNORECASE)
         if bonus_p.search(in_track.title):
-            in_track.flags.add_flag(FlagCodes.p_bonus_track)
+            in_track.flags.add_flag(TrackFlagCodes.p_bonus_track)
+
+    def test_album_track_intro(self, in_track: Track):
+        '''
+        Test the track to see if it is an introduction to
+        another track, or possibly for the album itself.
+        '''
+        intro_p = re.compile(r'[\s\W]?Intro', re.IGNORECASE)
+        if intro_p.search(in_track.title):
+            in_track.flags.add_flag(TrackFlagCodes.p_intro)
+
+    def test_album_track_reprise(self, in_track: Track):
+        '''
+        Test the track to see if it is labeled as a
+        reprise, either to the album, or to a previous
+        track on the album.
+        '''
+        reprise_p = re.compile(r'[\s\W]?Reprise', re.IGNORECASE)
+        if reprise_p.search(in_track.title):
+            in_track.flags.add_flag(TrackFlagCodes.p_reprise)
+
+    def test_intro_reprise_presence(self, in_album: Album):
+        '''
+        Test to see if both an intro and reprise is
+        contained in the album, and add an additional
+        album level flag to identify it.
+        '''
+        reprise = False
+        intro = False
+        for dsc in sorted(in_album.discs):
+            for trk in sorted(in_album.discs[dsc].tracks,
+                              key=lambda x: x.track_no):
+                if TrackFlagCodes.p_intro in trk.flags:
+                    intro = True
+                if TrackFlagCodes.p_reprise in trk.flags:
+                    reprise = True
+                if intro and reprise:
+                    in_album.flags.add_flag(AlbumFlagCodes.p_intro_reprise)
+                    break