restructure shared modules + fix documentation

.gitignore

@@ -23,7 +23,7 @@ config.yml
 # build/dev/doc directories
 dist/
 .grip/
-_site/
+.docs/
 docs/modules.rst
 docs/syncify*.rst
 

logging.yml

@@ -16,10 +16,10 @@ formatters:
 
 filters:
   console:
-    (): "syncify.utils.logger.LogConsoleFilter"
+    (): "syncify.shared.logger.LogConsoleFilter"
     module_width: 40
   file:
-    (): "syncify.utils.logger.LogFileFilter"
+    (): "syncify.shared.logger.LogFileFilter"
     module_width: 40
 
 handlers:
@@ -50,7 +50,7 @@ handlers:
     stream: ext://sys.stdout
 
   file:
-    class: syncify.utils.logger.CurrentTimeRotatingFileHandler
+    class: syncify.shared.logger.CurrentTimeRotatingFileHandler
     level: DEBUG
     formatter: extended
     filters: ["file"]
@@ -69,7 +69,7 @@ loggers:
 
   test:
     <<: *logger
-    handlers: [console_stat]
+    handlers: [console_debug]
 
   dev:
     <<: *logger

main.py

@@ -5,26 +5,27 @@
 import re
 import sys
 import traceback
-from collections.abc import Mapping
+from collections.abc import Mapping, Callable
 from datetime import date, datetime, timedelta
 from os.path import basename, dirname, join, relpath, splitext
 from time import perf_counter
-from typing import Any, Callable
+from typing import Any
 
 from syncify import PROGRAM_NAME
 from syncify.config import Config, ConfigLibraryDifferences, ConfigMissingTags, ConfigRemote, ConfigLocal
-from syncify.exception import ConfigError
-from syncify.fields import LocalTrackField
+from syncify.shared.exception import ConfigError
+from syncify.local.track.fields import LocalTrackField
 from syncify.local.collection import LocalCollection
 from syncify.local.track import LocalTrack, SyncResultTrack
 from syncify.processors.base import DynamicProcessor, dynamicprocessormethod
-from syncify.remote.api import RemoteAPI
-from syncify.remote.enums import RemoteObjectType
-from syncify.remote.object import RemoteAlbum
+from syncify.shared.remote.api import RemoteAPI
+from syncify.shared.remote.enums import RemoteObjectType
+from syncify.shared.remote.object import RemoteAlbum
 from syncify.report import report_playlist_differences, report_missing_tags
-from syncify.utils.helpers import get_user_input, UnitIterable, to_collection
-from syncify.utils.logger import SyncifyLogger, STAT, CurrentTimeRotatingFileHandler, REPORT
-from syncify.utils.printers import print_logo, print_line, print_time
+from syncify.shared.utils import get_user_input, to_collection
+from syncify.shared.types import UnitIterable
+from syncify.shared.logger import SyncifyLogger, STAT, CurrentTimeRotatingFileHandler, REPORT
+from syncify.printers import print_logo, print_line, print_time
 
 
 class Syncify(DynamicProcessor):

readme.py

@@ -1,4 +1,4 @@
-from syncify.exception import SafeDict
+from syncify.shared.exception import SafeDict
 from syncify.local.track import TRACK_FILETYPES
 from syncify.local.playlist import PLAYLIST_FILETYPES
 from syncify.local.library import LIBRARY_CLASSES, LocalLibrary

src/syncify/__init__.py

@@ -2,9 +2,10 @@
 
 PROGRAM_NAME = "Syncify"
 __version__ = "0.3"
-PROGRAM_OWNER_NAME = "geo-martino"
+PROGRAM_OWNER_NAME = "George Martin Marino"
+PROGRAM_OWNER_USER = "geo-martino"
 PROGRAM_OWNER_EMAIL = f"gm.engineer+{PROGRAM_NAME.lower()}@pm.me"
-PROGRAM_URL = f"https://github.com/{PROGRAM_OWNER_NAME}/{PROGRAM_NAME.casefold()}"
+PROGRAM_URL = f"https://github.com/{PROGRAM_OWNER_USER}/{PROGRAM_NAME.casefold()}"
 
 MODULE_ROOT: str = basename(dirname(__file__))
 PACKAGE_ROOT: str = dirname(dirname(dirname(__file__)))

src/syncify/config.py

@@ -6,34 +6,35 @@
 import os
 import sys
 from abc import ABCMeta, abstractmethod
-from collections.abc import Mapping, Collection, Callable
+from collections.abc import Mapping, Collection, Callable, Iterable
 from copy import deepcopy
 from dataclasses import dataclass
 from datetime import datetime
 from os.path import isabs, join, dirname, splitext, exists
-from typing import Any, Self, get_args, Iterable
+from typing import Any, Self, get_args
 
 import yaml
 
 from syncify import PACKAGE_ROOT, MODULE_ROOT
-from syncify.abstract import NamedObject
-from syncify.abstract.enums import TagField
-from syncify.abstract.misc import PrettyPrinter, Filter
-from syncify.abstract.object import Library
-from syncify.api import APIAuthoriser, RequestHandler
-from syncify.exception import ConfigError, SyncifyError
-from syncify.fields import LocalTrackField
+from syncify.shared.core.base import NamedObject
+from syncify.shared.core.enums import TagField
+from syncify.shared.core.misc import PrettyPrinter, Filter
+from syncify.shared.core.object import Library
+from syncify.shared.api.authorise import APIAuthoriser
+from syncify.shared.api.request import RequestHandler
+from syncify.shared.exception import ConfigError, SyncifyError
+from syncify.local.track.fields import LocalTrackField
 from syncify.local.collection import LocalCollection
 from syncify.local.exception import InvalidFileType, FileDoesNotExistError
 from syncify.local.library import MusicBee, LocalLibrary
 from syncify.processors.compare import Comparer
-from syncify.remote.api import RemoteAPI
-from syncify.remote.base import RemoteObject
-from syncify.remote.library import RemoteLibrary
-from syncify.remote.object import PLAYLIST_SYNC_KINDS, RemotePlaylist
-from syncify.remote.processors.check import RemoteItemChecker
-from syncify.remote.processors.search import RemoteItemSearcher
-from syncify.remote.processors.wrangle import RemoteDataWrangler
+from syncify.shared.remote.api import RemoteAPI
+from syncify.shared.remote.base import RemoteObject
+from syncify.shared.remote.library import RemoteLibrary
+from syncify.shared.remote.object import PLAYLIST_SYNC_KINDS, RemotePlaylist
+from syncify.shared.remote.processors.check import RemoteItemChecker
+from syncify.shared.remote.processors.search import RemoteItemSearcher
+from syncify.shared.remote.processors.wrangle import RemoteDataWrangler
 from syncify.report import report_missing_tags
 from syncify.spotify import SPOTIFY_NAME
 from syncify.spotify.api import SpotifyAPI
@@ -42,8 +43,8 @@
 from syncify.spotify.object import SpotifyPlaylist
 from syncify.spotify.processors.processors import SpotifyItemChecker, SpotifyItemSearcher
 from syncify.spotify.processors.wrangle import SpotifyDataWrangler
-from syncify.utils.helpers import to_collection
-from syncify.utils.logger import LOGGING_DT_FORMAT, SyncifyLogger
+from syncify.shared.utils import to_collection
+from syncify.shared.logger import LOGGING_DT_FORMAT, SyncifyLogger
 
 
 def _get_local_track_tags(tags: Any) -> tuple[LocalTrackField, ...]:

src/syncify/local/__init__.py

@@ -1,2 +0,0 @@
-from ._base import LocalItem
-from ._file import File, open_image, get_image_bytes

src/syncify/local/_base.py → src/syncify/local/base.py

@@ -1,7 +1,7 @@
 from abc import ABCMeta
 
-from syncify.abstract import Item
-from syncify.local._file import File
+from syncify.shared.core.base import Item
+from syncify.local.file import File
 
 
 class LocalItem(File, Item, metaclass=ABCMeta):

src/syncify/local/collection.py

@@ -9,20 +9,21 @@
 from os.path import splitext, join, basename, exists, isdir
 from typing import Any
 
-from syncify.abstract import Item
-from syncify.abstract.collection import ItemCollection
-from syncify.abstract.enums import Fields, TagField, TagFields
-from syncify.abstract.object import Track, Library, Folder, Album, Artist, Genre
-from syncify.exception import SyncifyKeyError
-from syncify.fields import LocalTrackField
-from syncify.local._base import LocalItem
+from syncify.shared.core.base import Item
+from syncify.shared.core.collection import ItemCollection
+from syncify.shared.core.enums import Fields, TagField, TagFields
+from syncify.shared.core.object import Track, Library, Folder, Album, Artist, Genre
+from syncify.shared.exception import SyncifyKeyError
+from syncify.local.track.fields import LocalTrackField
+from syncify.local.base import LocalItem
 from syncify.local.exception import LocalCollectionError
 from syncify.local.track import LocalTrack, SyncResultTrack, load_track, TRACK_FILETYPES
-from syncify.remote.enums import RemoteIDType
-from syncify.remote.processors.wrangle import RemoteDataWrangler
-from syncify.utils import UnitCollection
-from syncify.utils.helpers import get_most_common_values, to_collection, UnitIterable, align_and_truncate, get_max_width
-from syncify.utils.logger import SyncifyLogger, STAT
+from syncify.shared.remote.enums import RemoteIDType
+from syncify.shared.remote.processors.wrangle import RemoteDataWrangler
+from syncify.shared.types import UnitCollection
+from syncify.shared.utils import get_most_common_values, to_collection, align_and_truncate, get_max_width
+from syncify.shared.types import UnitIterable
+from syncify.shared.logger import SyncifyLogger, STAT
 
 __max_str = "z" * 50
 

src/syncify/local/exception.py

@@ -1,6 +1,6 @@
 from typing import Any
 
-from syncify.exception import SyncifyError
+from syncify.shared.exception import SyncifyError
 
 
 class LocalError(SyncifyError):

src/syncify/local/library/__init__.py

@@ -1,4 +1,4 @@
-from ._library import LocalLibrary
-from ._musicbee import MusicBee
+from .library import LocalLibrary
+from .musicbee import MusicBee
 
 LIBRARY_CLASSES = frozenset({LocalLibrary, MusicBee})

src/syncify/local/library/_library.py → src/syncify/local/library/library.py

@@ -3,19 +3,19 @@
 from os.path import splitext, join, exists, basename
 from typing import Any
 
-from syncify.abstract.misc import Result, Filter
-from syncify.abstract.object import Playlist, Library
-from syncify.exception import SyncifyError
-from syncify.fields import LocalTrackField
+from syncify.shared.core.misc import Result, Filter
+from syncify.shared.core.object import Playlist, Library
+from syncify.shared.exception import SyncifyError
+from syncify.local.track.fields import LocalTrackField
 from syncify.local.collection import LocalCollection, LocalFolder, LocalAlbum, LocalArtist, LocalGenres
 from syncify.local.exception import LocalCollectionError
 from syncify.local.playlist import PLAYLIST_FILETYPES, LocalPlaylist, load_playlist
 from syncify.local.track import TRACK_CLASSES, LocalTrack, load_track
 from syncify.processors.sort import ItemSorter
-from syncify.remote.processors.wrangle import RemoteDataWrangler
-from syncify.utils import UnitCollection, UnitIterable
-from syncify.utils.helpers import align_and_truncate, get_max_width, correct_platform_separators
-from syncify.utils.logger import REPORT
+from syncify.shared.remote.processors.wrangle import RemoteDataWrangler
+from syncify.shared.types import UnitCollection, UnitIterable
+from syncify.shared.utils import align_and_truncate, get_max_width, correct_platform_separators
+from syncify.shared.logger import REPORT
 
 
 class LocalLibrary(LocalCollection[LocalTrack], Library[LocalTrack]):

src/syncify/local/library/_musicbee.py → src/syncify/local/library/musicbee.py

@@ -9,14 +9,14 @@
 from lxml import etree
 from lxml.etree import iterparse
 
-from syncify.local import File
+from syncify.local.file import File
 from syncify.local.exception import MusicBeeIDError, XMLReaderError, MusicBeeError, FileDoesNotExistError
-from syncify.local.library._library import LocalLibrary
+from syncify.local.library.library import LocalLibrary
 from syncify.local.playlist import LocalPlaylist
 from syncify.local.track import LocalTrack
-from syncify.remote.processors.wrangle import RemoteDataWrangler
-from syncify.utils import UnitCollection, Number
-from syncify.utils.helpers import correct_platform_separators
+from syncify.shared.remote.processors.wrangle import RemoteDataWrangler
+from syncify.shared.types import UnitCollection, Number
+from syncify.shared.utils import correct_platform_separators
 
 
 class MusicBee(LocalLibrary, File):

src/syncify/local/playlist/__init__.py

@@ -1,5 +1,5 @@
-from ._m3u import M3U
-from ._match import LocalMatcher
-from ._playlist import LocalPlaylist
-from ._utils import PLAYLIST_CLASSES, PLAYLIST_FILETYPES, load_playlist
-from ._xautopf import XAutoPF
+from .m3u import M3U
+from .match import LocalMatcher
+from .base import LocalPlaylist
+from .utils import PLAYLIST_CLASSES, PLAYLIST_FILETYPES, load_playlist
+from .xautopf import XAutoPF

src/syncify/local/playlist/_playlist.py → src/syncify/local/playlist/base.py

@@ -4,15 +4,15 @@
 from datetime import datetime
 from os.path import dirname, join, getmtime, getctime, exists
 
-from syncify.abstract.misc import Result
-from syncify.abstract.object import Playlist
-from syncify.local import File
+from syncify.shared.core.misc import Result
+from syncify.shared.core.object import Playlist
+from syncify.local.file import File
 from syncify.local.collection import LocalCollection
-from syncify.local.playlist._match import LocalMatcher
+from syncify.local.playlist.match import LocalMatcher
 from syncify.local.track import LocalTrack, load_track
 from syncify.processors.limit import ItemLimiter
 from syncify.processors.sort import ItemSorter
-from syncify.remote.processors.wrangle import RemoteDataWrangler
+from syncify.shared.remote.processors.wrangle import RemoteDataWrangler
 
 
 class LocalPlaylist(LocalCollection[LocalTrack], Playlist[LocalTrack], File, metaclass=ABCMeta):

src/syncify/local/playlist/_m3u.py → src/syncify/local/playlist/m3u.py

@@ -3,12 +3,12 @@
 from dataclasses import dataclass
 from os.path import exists, dirname
 
-from syncify.abstract.misc import Result
-from syncify.local.playlist._match import LocalMatcher
-from syncify.local.playlist._playlist import LocalPlaylist
+from syncify.shared.core.misc import Result
+from syncify.local.playlist.match import LocalMatcher
+from syncify.local.playlist.base import LocalPlaylist
 from syncify.local.track import LocalTrack
-from syncify.remote.processors.wrangle import RemoteDataWrangler
-from syncify.utils import UnitCollection
+from syncify.shared.remote.processors.wrangle import RemoteDataWrangler
+from syncify.shared.types import UnitCollection
 
 
 @dataclass(frozen=True)

src/syncify/local/playlist/_match.py → src/syncify/local/playlist/match.py

@@ -3,14 +3,14 @@
 from os.path import exists
 from typing import Any, Self
 
-from syncify.abstract.enums import Fields
-from syncify.abstract.misc import Result
+from syncify.shared.core.enums import Fields
+from syncify.shared.core.misc import Result
 from syncify.local.track import LocalTrack
 from syncify.processors.base import MusicBeeProcessor
 from syncify.processors.compare import Comparer
 from syncify.processors.sort import ItemSorter
-from syncify.utils import UnitSequence, UnitCollection
-from syncify.utils.helpers import to_collection
+from syncify.shared.types import UnitSequence, UnitCollection
+from syncify.shared.utils import to_collection
 
 
 @dataclass(frozen=True)