modernize python stack + add type safety

.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# local testing file
+sandbox.py

.pre-commit-config.yaml

@@ -0,0 +1,35 @@
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v2.3.0
+    hooks:
+    -   id: check-yaml
+        args: [--unsafe]
+    -   id: end-of-file-fixer
+    -   id: trailing-whitespace
+-   repo: local
+    hooks:
+    -   id: ruff fix
+        name: Check and fix Python linting with ruff
+        entry: ruff check
+        types: [python]
+        language: system
+    -   id: ruff format
+        name: Autoformat Python files with ruff
+        entry: ruff format
+        types: [python]
+        language: system
+    -   id: pyright
+        name: Type checking with pyright
+        entry: pyright
+        types: [python]
+        language: system
+# -   repo: https://github.com/jendrikseipp/vulture
+#     rev: 'v2.14'
+#     hooks:
+#     -   id: vulture
+#         name: Check unused Python code
+-   repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.5.14
+    hooks:
+    -   id: uv-lock
+        name: Check if uv.lock is up to date

.python-version

@@ -0,0 +1 @@
+3.11

CONTRIBUTING.md

@@ -1 +1,9 @@
 # Contributing
+
+### 🔧 Quickstart
+- Install [`uv`](https://github.com/astral-sh/uv)
+
+```bash
+uv sync --all-packages
+pre-commit install
+```

pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "api-python"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "requests>=2.32.4",
+]
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.2.0",
+    "pyright>=1.1.403",
+    "ruff>=0.12.4",
+]
+
+[tool.pyright]
+reportIncompatibleMethodOverride = true
+typeCheckingMode = "strict"
+
+[tool.ruff]
+src = [".", "retroachievements"]
+line-length = 88
+
+[tool.ruff.lint]
+extend-select = ["I"]

retroachievements/__init__.py

@@ -8,7 +8,9 @@
 """
 
 __title__ = "retroachievements-api"
-__authors__ = "drisc"
+__authors__ = "drisc, amine456"
 __version__ = "1.0.0"
 
 from .client import RAClient
+
+__all__ = ["RAClient"]

retroachievements/base.py

@@ -0,0 +1,43 @@
+import requests
+
+from retroachievements import __version__
+
+_BASE_URL = "https://retroachievements.org/API/"
+
+
+class BaseRAClient:
+    """
+    Main class for accessing the RetroAchievements Web API
+    """
+
+    headers = {"User-Agent": "RetroAchievements-api-python/" + __version__}
+
+    def __init__(self, api_key: str):
+        self.api_key = api_key
+
+    def url_params(self, params: dict[str, str | int | None] | None = None):
+        """
+        Inserts the auth and query params into the request
+        """
+        if params is None:
+            params = {}
+        params.update({"y": self.api_key})
+        return params
+
+    # URL construction
+    def call_api(
+        self,
+        endpoint: str | None = None,
+        params: dict[str, str | int | None] | None = None,
+        timeout: int = 30,
+        headers: dict[str, str] | None = None,
+    ):
+        if endpoint is None:
+            endpoint = ""
+        req = requests.get(
+            f"{_BASE_URL}{endpoint}",
+            params=self.url_params(params),
+            timeout=timeout,
+            headers=headers,
+        )
+        return req