Merge pull request #4 from Nebulino/tag_methods

Sixth Pre-Release. Still a long way...

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...
 

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('####################################################################');
+}

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')

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<Tag> 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<List<Tag>> 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<List<Album>> 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<List<Artist>> 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<List<Tag>> 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<List<Track>> 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<List<Chart>> 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]));
+  }
+}

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,13 +23,15 @@ class Scrobblenaut {
   ChartMethods _chartMethods;
   GeoMethods _geoMethods;
   LibraryMethods _libraryMethods;
+  TagMethods _tagMethods;
 
   Scrobblenaut._(this._api) {
     _albumMethods = AlbumMethods(_api);
     _artistMethods = ArtistMethods(_api);
     _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;
 }

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