From 6ddf8ac53d6277b543e668d78f9001782f0b8960 Mon Sep 17 00:00:00 2001 From: Nebulino Date: Tue, 14 Apr 2020 15:45:04 +0200 Subject: [PATCH] Sixth Pre-Release. Still a long way... - Implemented Tag Methods. - Fixed Tag attributes. - Updated the changelog. - Added tag example. - Updated the README. --- CHANGELOG.md | 9 ++ example/tag_methods_example.dart | 71 ++++++++++++ lib/src/lastfm/tag.dart | 12 +- lib/src/methods/tag_methods.dart | 181 +++++++++++++++++++++++++++++++ lib/src/scrobblenaut.dart | 6 + pubspec.yaml | 2 +- 6 files changed, 273 insertions(+), 8 deletions(-) create mode 100644 example/tag_methods_example.dart create mode 100644 lib/src/methods/tag_methods.dart diff --git a/CHANGELOG.md b/CHANGELOG.md index 09b49df..1c9da7b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,12 @@ +## 0.1.5 +#### Sixth Pre-Release. Still a long way... + +- Implemented Tag Methods. +- Fixed Tag attributes. +- Updated the changelog. +- Added tag example. +- Updated the README. + ## 0.1.4 #### Fifth Pre-Release. Still a long way... diff --git a/example/tag_methods_example.dart b/example/tag_methods_example.dart new file mode 100644 index 0000000..bb25de3 --- /dev/null +++ b/example/tag_methods_example.dart @@ -0,0 +1,71 @@ +import 'package:scrobblenaut/lastfm.dart'; +import 'package:scrobblenaut/scrobblenaut.dart'; + +import 'api_values.dart'; + +// Just an example of use. +void main() async { + print('####################################################################'); + + final lastFMAuth = await LastFM.authenticate( + apiKey: APIValues.API, + apiSecret: APIValues.secret, + username: APIValues.username, + password: APIValues.password, + sessionKey: APIValues.sessionKey, + ); + + final scrobblenaut = Scrobblenaut(lastFM: lastFMAuth); + + print('############################tag.getInfo#############################'); + + // tag.getInfo + final tagGetInfo = (await scrobblenaut.tag.getInfo(tag: 'anime')); + print('Tag Name: ${tagGetInfo.name} | Tag total: ${tagGetInfo.total}'); + + print('############################tag.getSimilar##########################'); + + // tag.getSimilar + (await scrobblenaut.tag.getSimilar(tag: 'anime'))?.forEach((Tag tag) { + print('Similar Tag Name: ${tag.name}'); + }); + + print('##########################tag.getTopAlbums##########################'); + + // tag.getTopAlbums + (await scrobblenaut.tag.getTopAlbums(tag: 'anime'))?.forEach((Album album) { + print('Top Album Name: ${album.name}'); + }); + + print('########################tag.getTopArtists###########################'); + + // tag.getTopArtists + (await scrobblenaut.tag.getTopArtists(tag: 'anime')) + ?.forEach((Artist artist) { + print('Top Artist Name: ${artist.name}'); + }); + + print('##########################tag.getTopTags############################'); + + // tag.getTopTags + (await scrobblenaut.tag.getTopTags())?.forEach((Tag tag) { + print('Top Tag Name: ${tag.name}'); + }); + + print('########################tag.getTopTracks############################'); + + // tag.getTopTracks + (await scrobblenaut.tag.getTopTracks(tag: 'anime'))?.forEach((Track track) { + print('Top Track Name: ${track.name} | Top Track URL: ${track.url}'); + }); + + print('#######################tag.getWeeklyChartList#######################'); + + // tag.getWeeklyChartList + (await scrobblenaut.tag.getWeeklyChartList(tag: 'anime')) + ?.forEach((Chart chart) { + print('Chart FromDate: ${chart.fromDate} | Chart ToDate: ${chart.toDate}'); + }); + + print('####################################################################'); +} diff --git a/lib/src/lastfm/tag.dart b/lib/src/lastfm/tag.dart index 8be85c5..6b01166 100644 --- a/lib/src/lastfm/tag.dart +++ b/lib/src/lastfm/tag.dart @@ -20,23 +20,21 @@ class Tag { @JsonKey(name: 'count') int count; - // TODO: what's this? - /// The total number of usage of this tag. + /// The total number of usage of this tag from a user. @JsonKey(name: 'total', fromJson: LastFMValueNormalizer.NumberToInt) int total; - // TODO: what's this? + /// The total number of usage of this tag. @JsonKey(name: 'reach', fromJson: LastFMValueNormalizer.NumberToInt) int reach; - // TODO: what's this? /// The number of usage applied from a user. @JsonKey(name: 'taggings', fromJson: LastFMValueNormalizer.NumberToInt) int taggings; - // TODO: another incoherency? is bool? 1 / 0 - @JsonKey(name: 'streamable') - String streamable; + /// If True, this tag can be used as a Radio Station. + @JsonKey(name: 'streamable', fromJson: LastFMValueNormalizer.NumberToBool) + bool streamable; /// The wiki of the tag. @JsonKey(name: 'wiki') diff --git a/lib/src/methods/tag_methods.dart b/lib/src/methods/tag_methods.dart new file mode 100644 index 0000000..60887ce --- /dev/null +++ b/lib/src/methods/tag_methods.dart @@ -0,0 +1,181 @@ +/** + * Scrobblenaut - A deadly simple Last.FM API Wrapper for Dart. + * Copyright (c) 2020 Nebulino + */ + +import 'package:meta/meta.dart'; +import 'package:scrobblenaut/lastfm.dart'; +import 'package:scrobblenaut/src/core/lastfm.dart'; +import 'package:scrobblenaut/src/core/request.dart'; +import 'package:scrobblenaut/src/core/request_mode.dart'; + +/// This contains all the methods about a [Tag]. +class TagMethods { + final LastFM _api; + + TagMethods(this._api); + + /// Get the metadata for a tag. + /// + /// https://www.last.fm/api/show/tag.getInfo + Future getInfo({ + @required String tag, + Language lang = Language.en, + }) async { + final parameters = { + 'tag': tag, + 'lang': lang?.code, + }; + + final request = + Request(api: _api, method: 'tag.getInfo', parameters: parameters); + + return (Tag.fromJson((await request.send(mode: RequestMode.GET))['tag'])); + } + + /// Search for tags similar to this one. + /// Returns tags ranked by similarity, based on listening data. + /// + /// https://www.last.fm/api/show/tag.getSimilar + Future> getSimilar({ + @required String tag, + }) async { + final parameters = { + 'tag': tag, + }; + + final request = + Request(api: _api, method: 'tag.getSimilar', parameters: parameters); + + final response = await request.send(mode: RequestMode.GET); + + final similarTags = response['similartags']['tag']; + + return similarTags == null + ? null + : List.generate( + (similarTags as List).length, (i) => Tag.fromJson(similarTags[i])); + } + + /// Get the top albums tagged by this tag, ordered by tag count. + /// + /// https://www.last.fm/api/show/tag.getTopAlbums + Future> getTopAlbums({ + @required String tag, + int page = 1, + int limit = 50, + }) async { + final parameters = { + 'tag': tag, + 'page': page, + 'limit': limit, + }; + + final request = + Request(api: _api, method: 'tag.getTopAlbums', parameters: parameters); + + final response = await request.send(mode: RequestMode.GET); + + final topAlbums = response['albums']['album']; + + return topAlbums == null + ? null + : List.generate( + (topAlbums as List).length, (i) => Album.fromJson(topAlbums[i])); + } + + /// Get the top artists tagged by this tag, ordered by tag count. + /// + /// https://www.last.fm/api/show/tag.getTopArtists + Future> getTopArtists({ + @required String tag, + int page = 1, + int limit = 50, + }) async { + final parameters = { + 'tag': tag, + 'page': page, + 'limit': limit, + }; + + final request = + Request(api: _api, method: 'tag.getTopArtists', parameters: parameters); + + final response = await request.send(mode: RequestMode.GET); + + final topArtists = response['topartists']['artist']; + + return topArtists == null + ? null + : List.generate( + (topArtists as List).length, (i) => Artist.fromJson(topArtists[i])); + } + + /// Fetches the top global tags on Last.fm, + /// sorted by popularity (number of times used). + /// + /// https://www.last.fm/api/show/tag.getTopTags + Future> getTopTags() async { + final request = Request(api: _api, method: 'tag.getTopTags'); + + final response = await request.send(mode: RequestMode.GET); + + final topTags = response['toptags']['tag']; + + return topTags == null + ? null + : List.generate( + (topTags as List).length, (i) => Tag.fromJson(topTags[i])); + } + + /// Get the top tracks tagged by this tag, ordered by tag count. + /// + /// https://www.last.fm/api/show/tag.getTopTracks + Future> getTopTracks({ + @required String tag, + int page = 1, + int limit = 50, + }) async { + final parameters = { + 'tag': tag, + 'page': page, + 'limit': limit, + }; + + final request = + Request(api: _api, method: 'tag.getTopTracks', parameters: parameters); + + final response = await request.send(mode: RequestMode.GET); + + final topTracks = response['tracks']['track']; + + return topTracks == null + ? null + : List.generate( + (topTracks as List).length, (i) => Track.fromJson(topTracks[i])); + } + + /// Get a list of available charts for this tag, + /// expressed as date ranges which can be sent to the chart services. + /// + /// https://www.last.fm/api/show/tag.getWeeklyChartList. + Future> getWeeklyChartList({ + @required String tag, + }) async { + final parameters = { + 'tag': tag, + }; + + final request = Request( + api: _api, method: 'tag.getWeeklyChartList', parameters: parameters); + + final response = await request.send(mode: RequestMode.GET); + + final chartList = response['weeklychartlist']['chart']; + + return chartList == null + ? null + : List.generate( + (chartList as List).length, (i) => Chart.fromJson(chartList[i])); + } +} diff --git a/lib/src/scrobblenaut.dart b/lib/src/scrobblenaut.dart index 5b0b2bc..dd377cc 100644 --- a/lib/src/scrobblenaut.dart +++ b/lib/src/scrobblenaut.dart @@ -10,6 +10,7 @@ import 'package:scrobblenaut/src/methods/artist_methods.dart'; import 'package:scrobblenaut/src/methods/chart_methods.dart'; import 'package:scrobblenaut/src/methods/geo_methods.dart'; import 'package:scrobblenaut/src/methods/library_methods.dart'; +import 'package:scrobblenaut/src/methods/tag_methods.dart'; /// This connects all the various methods [LastFM] can provide. /// @@ -22,6 +23,7 @@ class Scrobblenaut { ChartMethods _chartMethods; GeoMethods _geoMethods; LibraryMethods _libraryMethods; + TagMethods _tagMethods; Scrobblenaut._(this._api) { _albumMethods = AlbumMethods(_api); @@ -29,6 +31,7 @@ class Scrobblenaut { _chartMethods = ChartMethods(_api); _geoMethods = GeoMethods(_api); _libraryMethods = LibraryMethods(_api); + _tagMethods = TagMethods(_api); } /// It creates a Scrobblenaut Session using a LastFM object. @@ -51,4 +54,7 @@ class Scrobblenaut { /// Use this to use [Library]'s methods. LibraryMethods get library => _libraryMethods; + + /// Use this to use [Tag]'s methods. + TagMethods get tag => _tagMethods; } diff --git a/pubspec.yaml b/pubspec.yaml index 55ff8f3..600609d 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -1,6 +1,6 @@ name: scrobblenaut description: A deadly simple Last.FM API Wrapper for Dart. -version: 0.1.4 +version: 0.1.5 homepage: https://github.com/Nebulino/Scrobblenaut issue_tracker: https://github.com/Nebulino/Scrobblenaut/issues