Add get_servers() and Server support (#101)

- Added ServerType Enum, ServerPlayer, Server and PrivateServer
- Added deprecated warning to get_instances method. Added new methods get_servers and get_private_servers
- Added docstrings to init functions, Server object does not inherit from BaseItem anymore, added equal and not equal checks to Server and PrivateServer objects and redid the wording on some already existing docstrings

roblox/bases/baseplace.py

@@ -8,9 +8,11 @@
 from typing import TYPE_CHECKING
 
 from ..bases.baseasset import BaseAsset
+from ..utilities.iterators import PageIterator, SortOrder
 
 if TYPE_CHECKING:
     from ..client import Client
+    from ..jobs import ServerType
 
 
 class BasePlace(BaseAsset):
@@ -40,6 +42,9 @@ async def get_instances(self, start_index: int = 0):
         This list always contains 10 items or fewer.
         For more items, add 10 to the start index and repeat until no more items are available.
 
+        !!! warning
+            This method has been deprecated. Please rectify any code that uses this method.        
+
         Arguments:
             start_index: Where to start in the server index.
         """
@@ -57,3 +62,62 @@ async def get_instances(self, start_index: int = 0):
             client=self._client,
             data=instances_data
         )
+
+    def get_servers(
+            self,
+            server_type: ServerType,
+            page_size: int = 10, 
+            sort_order: SortOrder = SortOrder.Descending, 
+            exclude_full_games: bool = False,
+            max_items: int = None
+    ) -> PageIterator:
+        """
+        Grabs the place's servers.
+
+        Arguments:
+            server_type: The type of servers to return.
+            page_size: How many servers should be returned for each page.
+            sort_order: Order in which data should be grabbed.
+            exclude_full_games: Whether to exclude full servers.
+            max_items: The maximum items to return when looping through this object.
+        Returns:
+            A PageIterator containing servers.
+        """
+        from ..jobs import Server
+
+        return PageIterator(
+            client=self._client,
+            url=self._client._url_generator.get_url("games", f"v1/games/{self.id}/servers/{server_type.value}"),
+            page_size=page_size,
+            max_items=max_items,
+            sort_order=sort_order,
+            extra_parameters={"excludeFullGames": exclude_full_games},
+            handler=lambda client, data: Server(client=client, data=data),
+        )
+
+    def get_private_servers(
+            self,
+            page_size: int = 10, 
+            sort_order: SortOrder = SortOrder.Descending, 
+            max_items: int = None
+    ) -> PageIterator:
+        """
+        Grabs the private servers of a place the authenticated user can access.
+
+        Arguments:
+            page_size: How many private servers should be returned for each page.
+            sort_order: Order in which data should be grabbed.
+            max_items: The maximum items to return when looping through this object.
+        Returns:
+            A PageIterator containing private servers.
+        """
+        from ..jobs import PrivateServer
+
+        return PageIterator(
+            client=self._client,
+            url=self._client._url_generator.get_url("games", f"v1/games/{self.id}/private-servers"),
+            page_size=page_size,
+            max_items=max_items,
+            sort_order=sort_order,
+            handler=lambda client, data: PrivateServer(client=client, data=data),
+        )

roblox/jobs.py

@@ -5,16 +5,19 @@
 """
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Optional
 
 if TYPE_CHECKING:
     from .client import Client
 
 from typing import List
+from enum import Enum
 
 from .bases.basejob import BaseJob
 from .bases.baseplace import BasePlace
 from .bases.baseuser import BaseUser
+from .bases.baseitem import BaseItem
+from .partials.partialuser import PartialUser
 
 
 class GameInstancePlayerThumbnail:
@@ -138,3 +141,106 @@ def __init__(self, client: Client, data: dict):
             ) for instance_data in data["Collection"]
         ]
         self.total_collection_size: int = data["TotalCollectionSize"]
+
+
+class ServerType(Enum):
+    """
+    Represents the type of server.
+    """
+
+    public = "Public"
+    friend = "Friend"
+
+
+class ServerPlayer(BaseUser):
+    """
+    Represents a player in a server.
+    
+    Attributes:
+        id: The player's user id.
+        name: The player's username.
+        display_name: The player's display name.
+        player_token: The player's token.
+    """
+
+    def __init__(self, client: Client, data: dict):
+        """
+        Arguments:
+            client: The Client this object belongs to.
+            data: A GameServerPlayerResponse object.
+        """
+
+        super().__init__(client=client, user_id=data["id"])
+
+        self.player_token: str = data["playerToken"]
+        self.name: str = data["name"]
+        self.display_name: str = data["displayName"]
+
+
+class Server(BaseItem):
+    """
+    Represents a public server.
+
+    Attributes:
+        id: The server's job id.
+        max_players: The maximum number of players that can be in the server at once.
+        playing: The amount of players in the server.
+        player_tokens: A list of thumbnail tokens for all the players in the server.
+        players: A list of ServerPlayer objects representing the players in the server. Only friends of the authenticated user will show up here.
+        fps: The server's fps.
+        ping: The server's ping.
+    """
+
+    def __init__(self, client: Client, data: dict):
+        """
+        Arguments:
+            client: The Client this object belongs to.
+            data: A GameServerResponse object.
+        """
+
+        self._client: Client = client
+
+        self.id: Optional[str] = data.get("id")
+        self.max_players: int = data["maxPlayers"]
+        self.playing: int = data.get("playing", 0)
+        self.player_tokens: List[str] = data["playerTokens"]
+        self.players: List[ServerPlayer] = [
+            ServerPlayer(client=self._client, data=player_data) 
+            for player_data in data["players"]
+        ]
+
+        self.fps: float = data.get("fps")
+        self.ping: Optional[int] = data.get("ping")
+
+
+class PrivateServer(Server):
+    """
+    Represents a private server.
+
+    Attributes:
+        id: The private server's job id.
+        vip_server_id: The private server's vipServerId.
+        max_players: The maximum number of players that can be in the server at once.
+        playing: The amount of players in the server.
+        player_tokens: A list of thumbnail tokens for all the players in the server.
+        players: A list of ServerPlayer objects representing the players in the server. Only friends of the authenticated user will show up here.
+        fps: The server's fps.
+        ping: The server's ping.
+        name: The private server's name.
+        access_code: The private server's access code.
+        owner: A PartialUser object representing the owner of the private server.
+    """
+
+    def __init__(self, client: Client, data: dict):
+        """
+        Arguments:
+            client: The Client this object belongs to.
+            data: A PrivateServerResponse object.
+        """
+
+        super().__init__(client=client, data=data)
+
+        self.name: str = data["name"]
+        self.vip_server_id: int = data["vipServerId"]
+        self.access_code: str = data["accessCode"]
+        self.owner: PartialUser = PartialUser(client=self._client, data=data["owner"])