Merge branch '3.0.0'

Author: SharpBit

CHANGELOG.md

@@ -1,6 +1,22 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
+## [3.0.0]
+### Added
+- Official API support (all endpoints implemented, all methods documented)
+- `Forbidden` error raised when code 403 received
+- New terminology! "BrawlAPI" refers to the [unofficial API](https://api.brawlapi.cf/v1) while "OfficialAPI" refers to the [official API](https://developer.brawlstars.com)
+### Changed (BREAKING)
+- The unofficial API's client will now be accessed as `brawlstats.BrawlAPI` (from `brawlstats.Client`)
+- The unofficial API's models will now be accessed as `brawlstats.brawlapi.ModelName`
+- The official API's client will be accessed by `brawlstats.OfficialAPI`
+- The official API's models will be accessed by `brawlstats.officialapi.ModelName`
+- `get_leaderboard()` will now require "brawlers" for the ranking type and the actual brawler name passed through the brawler kwarg.
+- `get_leaderboard()` `count` argument has been renamed to `limit`
+### Fixed
+- BrawlAPI `get_leaderboard` parameter documentation fixed
+- Arguments passed into functions that require player/club tags now properly get formatted correctly.
+
 ## [2.3.14] - 9/14/19
 ### Changed
 - Default timeout from 10 to 30
@@ -215,4 +231,22 @@ BREAKING CHANGES: Brawl Stars dev team changed "Band" to "Club". This update fix
 
 ## [2.0.0] - 11/19/18
 ### Added
-- Support for the brand new API at https://brawlapi.cf/api
+- Support for the brand new API at https://brawlapi.cf/api
+
+## [1.5.0] - 2/18/18
+### Added
+- Python 3.5 support!
+
+## [1.2.0] - 2/13/18
+### Changed
+- Base links for the new API changes
+
+## [1.1.12] - 2/7/18
+### Added
+- Essential core
+
+
+
+## [1.0.0]
+### Added
+- Request maker

README.rst

@@ -20,16 +20,16 @@ Brawl Stats
     :target: https://github.com/SharpBit/brawlstats/blob/master/LICENSE
     :alt: MIT License
 
-- This library is a sync and async wrapper the unofficial `Brawl Stars API`_.
+- This library is a sync and async wrapper for https://brawlapi.cf (BrawlAPI) and the official Brawl Stars API.
 - Python 3.5.3 or later is required.
-- To keep up with API changes, discussions, and status, I recommend you join the API's `discord server`_.
 
 Features
 ~~~~~~~~
 
-- Covers all of the API endpoints.
+- Covers all of the endpoints of both APIs.
 - Use the same client for sync and async usage.
-- Helper functions to access other game files such as maps and audio files.
+- Choose which API you want to use!
+- Access game constants such as maps, brawlers, and images.
 - Easy to use with an object oriented design.
 
 Installation
@@ -54,40 +54,40 @@ Documentation is being hosted on `Read the Docs`_.
 
 Examples
 ~~~~~~~~
-Examples are in the `examples folder`_.
-
+Examples are in the `examples folder`_. Within each folder, you will find:
 - ``sync.py`` shows you basic sync usage
 - ``async.py`` shows you basic async usage
-- ``discord_cog.py`` shows an example Discord Bot cog using `discord.py rewrite`_
+- ``discord_cog.py`` shows an example Discord Bot cog using `discord.py`_
 
 Misc
 ~~~~
 
-- If you are currently using this wrapper, feel free to star this repository :)
+- If you are currently using this wrapper, please star this repository :)
 - If you come across an issue in the wrapper, please `create an issue`_. Do **not** PM me on Discord for help.
-- If you need an API Key, create one using the `dashboard`_.
+- If you need an API Key for BrawlAPI, create one using the `dashboard`_. If you need one for the official API, visit https://developer.brawlstars.com
+- To receive help for using the BrawlAPI, I recommend you join BrawlAPI's `discord server`_.
 
 Contributing
 ~~~~~~~~~~~~
 Special thanks to this project's contributors ❤️
 
 - `4JR`_
-- `OrangutanGaming`_
-- `Stitch`_
 - `kjkui`_
 - `Kyber`_
 - `Pollen`_
+- `OrangutanGaming`_
+- `Stitch`_
 
 If you want to contribute, whether it be a bug fix or new feature, make sure to follow the `contributing guidelines`_.
 
-.. _Brawl Stars API: https://api.brawlapi.cf/v1
 .. _create an issue: https://github.com/SharpBit/brawlstats/issues
 .. _discord server: https://discord.me/BrawlAPI
 .. _Read the Docs: https://brawlstats.rtfd.io/
 .. _examples folder: https://github.com/SharpBit/brawlstats/tree/master/examples
-.. _discord.py rewrite: https://github.com/rapptz/discord.py/tree/rewrite
+.. _discord.py: https://github.com/rapptz/discord.py
 .. _contributing guidelines: https://github.com/SharpBit/brawlstats/blob/master/CONTRIBUTING.md
 .. _dashboard: https://brawlapi.cf/dashboard
+
 .. _4JR: https://github.com/fourjr
 .. _OrangutanGaming: https://github.com/OrangutanGaming
 .. _Stitch: https://github.com/Soumil07

brawlstats/__init__.py

@@ -1,14 +1,14 @@
-from .core import Client
+from .brawlapi import Client as BrawlAPI
+from .officialapi import Client as OfficialAPI
 from .errors import *
-from .models import *
 
 
 ############
 # METADATA #
 ############
 
 
-__version__ = 'v2.3.14'
+__version__ = 'v3.0.0'
 __title__ = 'brawlstats'
 __license__ = 'MIT'
 __author__ = 'SharpBit'

brawlstats/brawlapi/__init__.py

@@ -0,0 +1,2 @@
+from .core import Client
+from .models import *

brawlstats/core.py brawlstats/brawlapi/core.pybrawlstats/core.py renamed to brawlstats/brawlapi/core.py

@@ -10,16 +10,16 @@
 from cachetools import TTLCache
 from datetime import datetime
 
-from .errors import NotFoundError, Unauthorized, ServerError, RateLimitError, MaintenanceError, UnexpectedError
+from ..errors import NotFoundError, Unauthorized, ServerError, Forbidden, RateLimitError, MaintenanceError, UnexpectedError
 from .models import Player, Club, PartialClub, Events, Leaderboard, Constants, MiscData, BattleLog
-from .utils import API, bstag
+from .utils import API, bstag, typecasted
 
 log = logging.getLogger(__name__)
 
 
 class Client:
     """
-    This is a sync/async client class that lets you access the API.
+    This is a sync/async client class that lets you access the unofficial BrawlAPI.
 
     Parameters
     ------------
@@ -59,7 +59,7 @@ def __init__(self, token, session=None, timeout=30, is_async=False, **options):
         self.timeout = timeout
         self.prevent_ratelimit = options.get('prevent_ratelimit', False)
         self.lock = asyncio.Lock() if options.get('prevent_ratelimit') is True else None
-        self.api = API(options.get('base_url'))
+        self.api = API(options.get('base_url'), version=1)
 
         self.debug = options.get('debug', False)
         self.cache = TTLCache(540, 180)  # 3 requests/sec
@@ -72,7 +72,7 @@ def __init__(self, token, session=None, timeout=30, is_async=False, **options):
         }
 
     def __repr__(self):
-        return '<BrawlStats-Client async={} timeout={}>'.format(self.is_async, self.timeout)
+        return '<BrawlAPI-Client async={} timeout={} debug={}>'.format(self.is_async, self.timeout, self.debug)
 
     def close(self):
         return self.session.close()
@@ -98,6 +98,8 @@ def _raise_for_status(self, resp, text, url):
             return (data, resp)
         if code == 401:
             raise Unauthorized(url, code)
+        if code == 403:
+            raise Forbidden(url, code, data['message'])
         if code in (400, 404):
             raise NotFoundError(url, code)
         if code == 429:
@@ -162,13 +164,17 @@ async def _aget_model(self, url, model, key=None):
         else:
             data, resp = await self._arequest(url)
 
-        if model == Constants:
-            if key and not data.get(key):
-                raise KeyError('No such key for Brawl Stars constants "{}"'.format(key))
-            if key and data.get(key):
-                return model(self, resp, data.get(key))
-        if model in (PartialClub, BattleLog) and (isinstance(data, list) if model == PartialClub else 1):
+        # Club search
+        if model == PartialClub and isinstance(data, list):
             return [model(self, resp, data) for club in data]
+
+        if model == Constants:
+            if key:
+                if data.get(key):
+                    return model(self, resp, data.get(key))
+                else:
+                    raise KeyError('No such Constants key "{}"'.format(key))
+
         return model(self, resp, data)
 
     def _get_model(self, url, model, key=None):
@@ -177,15 +183,21 @@ def _get_model(self, url, model, key=None):
         data, resp = self._request(url)
         if self.prevent_ratelimit:
             time.sleep(1 / self.ratelimit[0])
-        if model == Constants:
-            if key and not data.get(key):
-                raise KeyError('No such key for Brawl Stars constants "{}"'.format(key))
-            if key and data.get(key):
-                return model(self, resp, data.get(key))
-        if model in (PartialClub, BattleLog) and (isinstance(data, list) if model == PartialClub else 1):
+
+        # Club search
+        if model == PartialClub and isinstance(data, list):
             return [model(self, resp, data) for club in data]
+
+        if model == Constants:
+            if key:
+                if data.get(key):
+                    return model(self, resp, data.get(key))
+                else:
+                    raise KeyError('No such Constants key "{}"'.format(key))
+
         return model(self, resp, data)
 
+    @typecasted
     def get_player(self, tag: bstag):
         """Get a player's stats.
 
@@ -203,6 +215,7 @@ def get_player(self, tag: bstag):
 
     get_profile = get_player
 
+    @typecasted
     def get_club(self, tag: bstag):
         """Get a club's stats.
 
@@ -218,28 +231,39 @@ def get_club(self, tag: bstag):
 
         return self._get_model(url, model=Club)
 
-    def get_leaderboard(self, lb_type: str, count: int=200, region='global'):
+    def get_leaderboard(self, lb_type: str, limit: int=200, region='global', brawler=None):
         """Get the top count players/clubs/brawlers.
 
         Parameters
         ----------
-        type: str
-            The type of leaderboard. Must be "players", "clubs", or the brawler leaderboard you are trying to access.
+        lb_type: str
+            The type of leaderboard. Must be "players", "clubs", "brawlers".
             Anything else will return a ValueError.
-        count: Optional[int] = 200
+        limit: Optional[int] = 200
             The number of top players or clubs to fetch.
             If count > 200, it will return a ValueError.
+        region: Optional[str] = "global"
+            The region to retrieve from. Must be a 2 letter country code or "global"
+        brawler: Optional[str|int] = None
+            The brawler name or ID.
 
         Returns Leaderboard
         """
-        lb_type = lb_type.lower()
-        if type(count) != int:
+        if brawler:
+            brawler = brawler.lower()
+        if brawler not in self.api.BRAWLERS and lb_type not in ['players', 'clubs', 'brawlers']:
+            raise ValueError("Please enter 'players', 'clubs' or 'brawlers'.")
+        if brawler in self.api.BRAWLERS.keys():
+            brawler = self.api.BRAWLERS[brawler]
+
+        if type(limit) != int:
             raise ValueError("Make sure 'count' is an int")
-        if lb_type not in self.api.BRAWLERS + ['players', 'clubs'] or not 0 < count <= 200:
-            raise ValueError("Please enter 'players', 'clubs' or a brawler or make sure 'count' is between 1 and 200.")
-        url = '{}/{}?count={}&region={}'.format(self.api.LEADERBOARD, lb_type, count, region)
-        if lb_type in self.api.BRAWLERS:
-            url = '{}/players?count={}&brawlers={}&region={}'.format(self.api.LEADERBOARD, count, lb_type, region)
+        if not 0 < limit <= 200:
+            raise ValueError('Make sure limit is between 1 and 200.')
+
+        url = '{}/{}?count={}&region={}'.format(self.api.LEADERBOARD, lb_type, limit, region)
+        if lb_type == 'brawlers':
+            url = '{}/players?count={}&brawlers={}&region={}'.format(self.api.LEADERBOARD, limit, lb_type, region)
 
         return self._get_model(url, model=Leaderboard)
 
@@ -249,25 +273,21 @@ def get_events(self):
         Returns Events"""
         return self._get_model(self.api.EVENTS, model=Events)
 
-    def get_constants(self, key=None):
-        """Gets Brawl Stars constants extracted from the app.
+    @typecasted
+    def get_battle_logs(self, tag: bstag):
+        """Get a player's battle logs.
 
         Parameters
         ----------
-        key: Optional[str] = None
-            Any key to get specific data.
-
-        Returns Constants
-        """
-        return self._get_model(self.api.CONSTANTS, model=Constants, key=key)
-
-    def get_misc(self):
-        """Gets misc data such as shop and season info.
+        tag: str
+            A valid player tag.
+            Valid characters: 0289PYLQGRJCUV
 
-        Returns MiscData
+        Returns BattleLog
         """
+        url = '{}?tag={}'.format(self.api.BATTLELOG, tag)
 
-        return self._get_model(self.api.MISC, model=MiscData)
+        return self._get_model(url, model=BattleLog)
 
     def search_club(self, club_name: str):
         """Searches for bands of the provided club name.
@@ -282,6 +302,26 @@ def search_club(self, club_name: str):
         url = self.api.CLUB_SEARCH + '?name=' + club_name
         return self._get_model(url, model=PartialClub)
 
+    def get_constants(self, key=None):
+        """Gets Brawl Stars constants extracted from the app.
+
+        Parameters
+        ----------
+        key: Optional[str] = None
+            Any key to get specific data.
+
+        Returns Constants
+        """
+        return self._get_model(self.api.CONSTANTS, model=Constants, key=key)
+
+    def get_misc(self):
+        """Gets misc data such as shop and season info.
+
+        Returns MiscData
+        """
+
+        return self._get_model(self.api.MISC, model=MiscData)
+
     def get_datetime(self, timestamp: str, unix=True):
         """Converts a %Y%m%dT%H%M%S.%fZ to a UNIX timestamp
         or a datetime.datetime object
@@ -301,18 +341,3 @@ def get_datetime(self, timestamp: str, unix=True):
             return int(time.timestamp())
         else:
             return time
-
-    def get_battle_logs(self, tag: bstag):
-        """Get a player's battle logs.
-
-        Parameters
-        ----------
-        tag: str
-            A valid player tag.
-            Valid characters: 0289PYLQGRJCUV
-
-        Returns List\[BattleLog, ..., BattleLog\]
-        """
-        url = '{}?tag={}'.format(self.api.BATTLELOG, tag)
-
-        return self._get_model(url, model=BattleLog)