roterminal 0.1.0__py3-none-any.whl

roterminal/__init__.py

@@ -0,0 +1,268 @@
+"""RoTerminal: live data on every Roblox game.
+
+Docs: https://roterminal.co/docs/sdks · Every endpoint: https://roterminal.co/docs/api
+
+    from roterminal import RoTerminal
+
+    rt = RoTerminal()  # reads ROTERMINAL_API_KEY
+    game = rt.games.retrieve("grow a garden")["data"]
+    print(game["name"], game["playing_now"])
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Optional, Union
+
+__version__ = "0.1.0"
+__all__ = ["RoTerminal", "RoTerminalError"]
+
+BASE_URL = "https://roterminal.co/api/v1"
+
+
+class RoTerminalError(Exception):
+    """An error from the API, with its code (https://roterminal.co/docs/errors)."""
+
+    def __init__(self, message: str, *, status: int, code: str, request_id: Optional[str] = None, doc_url: Optional[str] = None, param: Optional[str] = None, retry_after: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+        self.doc_url = doc_url
+        self.param = param
+        self.retry_after = retry_after
+
+    def __repr__(self) -> str:
+        return f"RoTerminalError(code={self.code!r}, status={self.status}, message={self.message!r})"
+
+
+class _Games:
+    def __init__(self, client: "RoTerminal") -> None:
+        self._c = client
+
+    def retrieve(self, game: Union[str, int]) -> dict:
+        """Retrieve a game. Everything on one Roblox game right now: players and its rank, the change over an hour and a day, highs, momentum, its genre, its developer, recent updates and how players moved after each, its closest rivals, its places on Roblox’s charts and the last 7 days of players.
+
+        https://roterminal.co/docs/api/games-retrieve
+        """
+        return self._c._get("/games/{game}", {"game": game})
+
+    def days(self, game: Union[str, int], *, days: Optional[int] = None) -> dict:
+        """List a game’s days. A game’s players day by day, newest first: the average, peak and low, the visits that day, and what happened (updates and events). Days run midnight to midnight, New York time.
+
+        https://roterminal.co/docs/api/games-days
+        """
+        return self._c._get("/games/{game}/days", {"game": game}, {"days": days})
+
+    def live(self, game: Union[str, int]) -> dict:
+        """Get live players. A game’s players this second, its rank on Roblox and its 24-hour high. Light enough to ask every 15 seconds, and it doesn’t count toward your daily calls.
+
+        https://roterminal.co/docs/api/games-live
+        """
+        return self._c._get("/games/{game}/live", {"game": game})
+
+    def developer(self, game: Union[str, int]) -> dict:
+        """Retrieve a game’s developer. Who makes a game, a Roblox group or one person: its owner, members, whether it’s verified, its rank among developers, everyone playing its games now, and each of its games.
+
+        https://roterminal.co/docs/api/games-developer
+        """
+        return self._c._get("/games/{game}/developer", {"game": game})
+
+    def search(self, q: str) -> dict:
+        """Search games. Find Roblox games by name: up to 8 matches with their universe ID, developer, genre and players now, the most played first.
+
+        https://roterminal.co/docs/api/games-search
+        """
+        return self._c._get("/games/search", {}, {"q": q})
+
+    def compare(self, games: list) -> dict:
+        """Compare games. Two to five games side by side: players now, the change over a day, momentum, rank in their genre, likes, the latest update and how it did, and the last 7 days of players for each.
+
+        https://roterminal.co/docs/api/games-compare
+        """
+        return self._c._get("/games/compare", {}, {"games": ",".join(str(g) for g in games)})
+
+    def top(self, *, list: Optional[str] = None, genre: Optional[str] = None, limit: Optional[int] = None) -> dict:
+        """List the most played games. Roblox games ranked by players right now, or only the games that came out in the last 30 days. Optionally one genre.
+
+        https://roterminal.co/docs/api/games-top
+        """
+        return self._c._get("/games/top", {}, {"list": list, "genre": genre, "limit": limit})
+
+    def rising(self, *, range: Optional[str] = None, genre: Optional[str] = None, limit: Optional[int] = None) -> dict:
+        """List rising games. The games gaining players fastest against a day ago or a week ago, each with its players now and then, the change, its genre and when it came out.
+
+        https://roterminal.co/docs/api/games-rising
+        """
+        return self._c._get("/games/rising", {}, {"range": range, "genre": genre, "limit": limit})
+
+    def screen(self, *, genre: Optional[str] = None, theme: Optional[str] = None, min_playing: Optional[int] = None, max_playing: Optional[int] = None, min_change_24h: Optional[float] = None, min_change_7d: Optional[float] = None, max_age_days: Optional[int] = None, min_like_pct: Optional[float] = None, sort: Optional[str] = None, limit: Optional[int] = None) -> dict:
+        """Screen games. Filter the 600 most played games by their numbers: genre, a theme in their names and descriptions, players, growth, age and likes, sorted the way you pick.
+
+        https://roterminal.co/docs/api/games-screen
+        """
+        return self._c._get("/games/screen", {}, {"genre": genre, "theme": theme, "min_playing": min_playing, "max_playing": max_playing, "min_change_24h": min_change_24h, "min_change_7d": min_change_7d, "max_age_days": max_age_days, "min_like_pct": min_like_pct, "sort": sort, "limit": limit})
+
+
+class _Trends:
+    def __init__(self, client: "RoTerminal") -> None:
+        self._c = client
+
+    def list(self, *, limit: Optional[int] = None) -> dict:
+        """List trends. What developers are making games about: the words in new games’ names, ranked by how many new games used them in the last 30 days against the 30 before, each with its biggest game.
+
+        https://roterminal.co/docs/api/trends-list
+        """
+        return self._c._get("/trends", {}, {"limit": limit})
+
+    def retrieve(self, word: Union[str, int]) -> dict:
+        """Retrieve a trend. One word, like horror or brainrot: how many new games used it in the last 30 days and the 30 before, how many games use it in all, everyone playing them now, and its biggest game. Use it to check whether an idea has been done.
+
+        https://roterminal.co/docs/api/trends-retrieve
+        """
+        return self._c._get("/trends/{word}", {"word": word})
+
+
+class _Genres:
+    def __init__(self, client: "RoTerminal") -> None:
+        self._c = client
+
+    def list(self) -> dict:
+        """List genres. Every genre on Roblox now: players, its share of everyone playing, the change on a day ago, how many games, its subgenres and its biggest games.
+
+        https://roterminal.co/docs/api/genres-list
+        """
+        return self._c._get("/genres", {})
+
+
+class _Charts:
+    def __init__(self, client: "RoTerminal") -> None:
+        self._c = client
+
+    def list(self) -> dict:
+        """List Roblox’s charts. Roblox’s own charts (Top Earning, Top Trending, Up-and-Coming and the rest), as RoTerminal keeps them day by day.
+
+        https://roterminal.co/docs/api/charts-list
+        """
+        return self._c._get("/charts", {})
+
+    def retrieve(self, chart: Union[str, int], *, limit: Optional[int] = None) -> dict:
+        """Retrieve a chart. One of Roblox’s charts now: its games in order, each with its players and its best place on the chart.
+
+        https://roterminal.co/docs/api/charts-retrieve
+        """
+        return self._c._get("/charts/{chart}", {"chart": chart}, {"limit": limit})
+
+
+class _Developers:
+    def __init__(self, client: "RoTerminal") -> None:
+        self._c = client
+
+    def retrieve(self, developer: Union[str, int]) -> dict:
+        """Retrieve a developer. A developer by name, a Roblox group or one person: its owner, members, whether it’s verified, its rank among developers, everyone playing its games now, and each of its games.
+
+        https://roterminal.co/docs/api/developers-retrieve
+        """
+        return self._c._get("/developers/{developer}", {"developer": developer})
+
+
+class _Roblox:
+    def __init__(self, client: "RoTerminal") -> None:
+        self._c = client
+
+    def retrieve(self) -> dict:
+        """Get players on Roblox. Everyone playing Roblox right now, the day’s high and low, the same time a week ago, and the last days’ averages and peaks.
+
+        https://roterminal.co/docs/api/roblox-retrieve
+        """
+        return self._c._get("/roblox", {})
+
+
+class _Me:
+    def __init__(self, client: "RoTerminal") -> None:
+        self._c = client
+
+    def retrieve(self) -> dict:
+        """Retrieve your account. Who the key belongs to, its plan, and the day’s calls: how many you’ve made, how many you have, and when they reset. It doesn’t count toward your daily calls.
+
+        https://roterminal.co/docs/api/me-retrieve
+        """
+        return self._c._get("/me", {})
+
+    def games(self) -> dict:
+        """List your games. Your own games, the ones My Games shows you: players now against usual for this time, the latest update and how players moved after it, and today’s alerts. Needs an API key.
+
+        https://roterminal.co/docs/api/me-games
+        """
+        return self._c._get("/me/games", {})
+
+
+
+class RoTerminal:
+    """The RoTerminal API.
+
+    api_key: your key (rta_...). Defaults to the ROTERMINAL_API_KEY environment
+        variable; without one, calls are made without a key (50 a day).
+    timeout: seconds before a request gives up.
+    max_retries: how many times to retry a 429 (per minute) or a 5xx.
+    """
+
+    def __init__(self, api_key: Optional[str] = None, *, base_url: str = BASE_URL, timeout: float = 20.0, max_retries: int = 2) -> None:
+        self.api_key = api_key if api_key is not None else os.environ.get("ROTERMINAL_API_KEY")
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.games = _Games(self)
+        self.trends = _Trends(self)
+        self.genres = _Genres(self)
+        self.charts = _Charts(self)
+        self.developers = _Developers(self)
+        self.roblox = _Roblox(self)
+        self.me = _Me(self)
+
+    def _get(self, path: str, at: dict, query: Optional[dict] = None) -> dict:
+        for key, value in at.items():
+            path = path.replace("{" + key + "}", urllib.parse.quote(str(value), safe=""))
+        params = {k: (",".join(str(x) for x in v) if isinstance(v, (list, tuple)) else v) for k, v in (query or {}).items() if v is not None and v != ""}
+        url = self.base_url + path + ("?" + urllib.parse.urlencode(params) if params else "")
+        headers = {"Accept": "application/json", "User-Agent": f"roterminal-python/{__version__}", "X-RoTerminal-Agent": "sdk/python"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        attempt = 0
+        while True:
+            request = urllib.request.Request(url, headers=headers)
+            try:
+                with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                    return json.loads(response.read().decode("utf-8"))
+            except urllib.error.HTTPError as e:
+                try:
+                    body: Any = json.loads(e.read().decode("utf-8"))
+                except Exception:
+                    body = {}
+                err = body.get("error", {}) if isinstance(body, dict) else {}
+                retry_after = _int(e.headers.get("Retry-After")) or err.get("retry_after")
+                again = (e.code == 429 and err.get("code") == "rate_limited") or e.code >= 500
+                if again and attempt < self.max_retries and (retry_after or 1) <= 60:
+                    time.sleep(retry_after or 2 ** attempt)
+                    attempt += 1
+                    continue
+                raise RoTerminalError(err.get("message") or f"RoTerminal answered {e.code}.", status=e.code, code=err.get("code", "internal_error"), request_id=err.get("request_id") or e.headers.get("X-Request-Id"), doc_url=err.get("doc_url"), param=err.get("param"), retry_after=retry_after) from None
+            except (urllib.error.URLError, TimeoutError) as e:
+                if attempt < self.max_retries:
+                    time.sleep(0.5 * 2 ** attempt)
+                    attempt += 1
+                    continue
+                raise RoTerminalError(f"Couldn't reach RoTerminal: {e}", status=0, code="network_error") from None
+
+
+def _int(value: Optional[str]) -> Optional[int]:
+    try:
+        return int(value) if value else None
+    except ValueError:
+        return None

roterminal-0.1.0.dist-info/METADATA

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: roterminal
+Version: 0.1.0
+Summary: Live data on every Roblox game: players now, history, rising games, trends and developers. The RoTerminal API for Python.
+Author: RoTerminal
+License-Expression: MIT
+Project-URL: Homepage, https://roterminal.co/docs/sdks
+Project-URL: Documentation, https://roterminal.co/docs/api
+Project-URL: Changelog, https://roterminal.co/docs/changelog
+Keywords: roblox,roblox-api,analytics,sdk,roterminal
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# roterminal
+
+Live data on every Roblox game, for Python: players right now, each game's history since Sep 27, 2026, rising games, trends, genres, Roblox's charts and the developers behind each game.
+
+```
+pip install roterminal
+```
+
+```python
+from roterminal import RoTerminal
+
+rt = RoTerminal()  # reads ROTERMINAL_API_KEY
+
+game = rt.games.retrieve("grow a garden")["data"]
+print(game["name"], game["playing_now"])
+
+for g in rt.games.rising(range="7d", limit=5)["data"]["games"]:
+    print(g["name"], g["change"])
+```
+
+The key is optional: without one you get 50 calls a day for each address. Create a free key at https://roterminal.co/account/developer.
+
+Errors raise `roterminal.RoTerminalError` with `code`, `status` and `request_id`.
+
+Every endpoint: https://roterminal.co/docs/api
+
+Version 0.1.0. MIT licence.

roterminal-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+roterminal/__init__.py,sha256=UQXDkg87L5j-9Sa1i4RCX-YpOE9qpW8N3rQJNdl7Ru4,12788
+roterminal/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+roterminal-0.1.0.dist-info/licenses/LICENSE,sha256=9p4hcueQ1_lQGelwMuBvld0UBIePT7rHkXsuGwyb04E,1082
+roterminal-0.1.0.dist-info/METADATA,sha256=s4lTOsRB_1jm_xe2cXjMYNLdhbcrt4hD0z3Y2X6yIh8,1503
+roterminal-0.1.0.dist-info/WHEEL,sha256=a-udL2m4V_6Yn8b-uKzWb12RjRxwwMo6ohYFM24tpaY,91
+roterminal-0.1.0.dist-info/top_level.txt,sha256=7pN8y1pO3MMvrkPB6vbMVddxNeTx71lr1M7aqsBrD8c,11
+roterminal-0.1.0.dist-info/RECORD,,

roterminal-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

roterminal-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Pixel Board Services Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

roterminal-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+roterminal