diff --git a/README.md b/README.md index b84acee..292ce04 100644 --- a/README.md +++ b/README.md @@ -209,14 +209,14 @@ To use a file-like object (e.g. BytesIO) instead of a file path, pass a ### 2.0.0 (Unreleased) - **BREAKING:** Store 'disc', 'disc_total', 'track' and 'track_total' values as int instead of str -- **BREAKING:** Remove 'get_image()' method in favor of 'images.any' property -- **BREAKING:** Move 'composer' field to 'extra' dict -- **BREAKING:** Remove 'audio_offset' attribute - **BREAKING:** TinyTagException no longer inherits LookupError - **BREAKING:** TinyTag subclasses are now private -- **BREAKING:** Remove 'ignore_errors' parameter for TinyTag.get() - **BREAKING:** Remove function to use custom audio file samples in tests - **BREAKING:** Remove support for Python 2 +- Mark 'ignore_errors' parameter for TinyTag.get() as obsolete +- Mark 'audio_offset' attribute as obsolete +- Deprecate 'composer' attribute in favor of 'extra.composer' +- Deprecate 'get_image()' method in favor of 'images.any' property - Provide access to custom metadata fields through the 'extra' dict - Provide access to all available images - Add more standard 'extra' fields diff --git a/tinytag/tests/test_all.py b/tinytag/tests/test_all.py index 5cb526c..ca3b66b 100644 --- a/tinytag/tests/test_all.py +++ b/tinytag/tests/test_all.py @@ -795,6 +795,19 @@ def test_show_hint_for_wrong_usage() -> None: assert exc_info.value.args[0] == 'Either filename or file_obj argument is required' +def test_deprecations() -> None: + file_path = os.path.join(testfolder, 'samples/id3v24-long-title.mp3') + with pytest.warns(DeprecationWarning): + tag = TinyTag.get(filename=file_path, image=True, ignore_errors=True) + with pytest.warns(DeprecationWarning): + assert tag.composer == tag.extra.get('composer') + with pytest.warns(DeprecationWarning): + assert tag.audio_offset is None + with pytest.warns(DeprecationWarning): + assert tag.images.any is not None + assert tag.get_image() == tag.images.any.data + + def test_to_str() -> None: tag = TinyTag.get(os.path.join(testfolder, 'samples/id3v22-test.mp3')) assert ( diff --git a/tinytag/tinytag.py b/tinytag/tinytag.py index a4483e2..3f9c4ae 100644 --- a/tinytag/tinytag.py +++ b/tinytag/tinytag.py @@ -41,6 +41,7 @@ from os import PathLike from sys import stderr from typing import Any, BinaryIO +from warnings import warn import base64 import io @@ -113,13 +114,17 @@ def get(cls, duration: bool = True, image: bool = False, encoding: str | None = None, - file_obj: BinaryIO | None = None) -> TinyTag: + file_obj: BinaryIO | None = None, + **kwargs: Any) -> TinyTag: """Return a tag object for an audio file.""" should_close_file = file_obj is None if filename and should_close_file: file_obj = open(filename, 'rb') # pylint: disable=consider-using-with if file_obj is None: raise ValueError('Either filename or file_obj argument is required') + if 'ignore_errors' in kwargs: + warn('ignore_errors argument is obsolete, and will be removed in a future ' + '2.x release', DeprecationWarning, stacklevel=2) try: file_obj.seek(0, os.SEEK_END) filesize = file_obj.tell() @@ -318,6 +323,27 @@ def _unpad(s: str) -> str: # strings in mp3 and asf *may* be terminated with a zero byte at the end return s.strip('\x00') + def get_image(self) -> bytes | None: + """Deprecated, use images.any instead.""" + warn('get_image() is deprecated, and will be removed in a future 2.x release. ' + 'Use images.any instead.', DeprecationWarning, stacklevel=2) + image = self.images.any + return image.data if image is not None else None + + @property + def audio_offset(self) -> None: + """Obsolete.""" + warn('audio_offset attribute is obsolete, and will be ' + 'removed in a future 2.x release', DeprecationWarning, stacklevel=2) + + @property + def composer(self) -> str | None: + """Deprecated, use extra.composer instead.""" + warn('composer attribute is deprecated, and will be removed in a future 2.x release. ' + 'Use extra.composer instead.', DeprecationWarning, stacklevel=2) + composer = self.extra.get('composer') + return composer if isinstance(composer, str) else None + class TagImages: """A class containing images embedded in an audio file."""