docs(functions): documentation for all functions + refine get()

Author: DRagssss

CHANGELOG.md

@@ -7,6 +7,25 @@ with the exception that all versions are currently `0.x.x` and may include break
 
 ---
 
+## [Unreleased]
+
+### Added
+
+- Use response headers to determine whether to parse HTTP responses into JSON
+- Added possibility for additional headers and proxies (handled by requests lib)
+- get() can also return `list` type as JSON can also be a list
+- Documentation for all functions
+
+### Changed
+
+`N/A`
+
+### Fixed
+
+`N/A`
+
+---
+
 ## [1.0.1] - 2025-12-20
 
 ### Added

src/hytale/blogs.py

@@ -4,15 +4,40 @@
 
 
 def get_blogs(limit=3) -> list[BlogPostExcerpt]:
+    """Get the most recent blogs with a snippet of the blog post's body.
+
+    Args:
+        limit (int, optional): The number of blog posts to retrieve. Defaults to 3.
+
+    Returns:
+        list[BlogPostExcerpt]: A list of blog post excerpts.
+    """
     data = get("/blog/post/published", limit=limit)
     return [BlogPostExcerpt.from_dict(item) for item in data]
 
 
 def get_blog(slug: str) -> BlogPost:
+    """Get a blog post with the entire body HTML content
+
+    Args:
+        slug (str): The slug provided by Hytale. For example https://hytale.com/news/2025/12/hytale-s-1st-faq has a slug of "hytale-s-1st-faq"
+
+    Returns:
+        BlogPost: The blog post.
+    """
     data = get(f"/blog/post/slug/{slug}")
     return BlogPost.from_dict(data)
 
 
 def get_blogs_time(year: int, month: int) -> list[BlogPostExcerpt]:
+    """Get the most recent blogs within a year and month
+
+    Args:
+        year (int): The year to filter blogs by.
+        month (int): The month to filter blogs by.
+
+    Returns:
+        list[BlogPostExcerpt]: A list of blog post excerpts.
+    """
     data = get(f"/blog/post/archive/{year}/{month}")
     return [BlogPostExcerpt.from_dict(item) for item in data]

src/hytale/http.py

@@ -1,4 +1,3 @@
-import json
 from typing import Union
 
 import requests
@@ -20,12 +19,32 @@
 )
 
 
-def get(path: str, sub_domain: str = "", **params) -> Union[dict, str]:
+def get(
+    path: str, sub_domain: str = "", headers=None, proxies=None, **params
+) -> Union[dict, list, str]:
+    """Send a get request to the Hytale API
+
+    Args:
+        path (str): The path of the endpoint (eg. "/blog/post/archive")
+        sub_domain (str, optional): The subdomain of the API (eg. "store."). Defaults to "".
+        headers (dict, optional): Additional headers to include in the request. Defaults to None.
+        proxies (dict, optional): Proxies to use for the request. Defaults to None.
+
+    Raises:
+        HytaleAPIError: Generic error
+        BlockedError: Error raised if cloudflare blocks the request (due to spam or headers misconfiguration)
+        HytaleAPIError: Generic HTTP error
+
+    Returns:
+        Union[dict, list, str]: Converted JSON response from the API if the response's Content-Type is `application/json`, otherwise a string.
+    """
     url = "https://" + sub_domain + BASE_URL + path
     try:
         response = _session.get(
             url,
             params=params,
+            headers=headers or {},
+            proxies=proxies,
             timeout=3,
         )
     except requests.RequestException as exc:
@@ -38,7 +57,9 @@ def get(path: str, sub_domain: str = "", **params) -> Union[dict, str]:
             f"Request failed [{response.status_code}]: {response.text}"
         )
 
-    try:
-        return json.loads(response.text)
-    except json.decoder.JSONDecodeError:
+    content_type = response.headers.get("Content-Type", "")
+
+    if content_type == "application/json":
+        return response.json()
+    else:
         return response.text

src/hytale/media.py

@@ -4,25 +4,50 @@
 
 
 def get_screenshots() -> list[Image]:
+    """Get screenshots from the media API.
+
+    Returns:
+        list[Image]: A list of images.
+    """
     data = get("/media/category/screenshots")
     return [Image.from_dict(item) for item in data]
 
 
 def get_desktop_wallpapers() -> list[Image]:
+    """Get desktop wallpapers from the media API.
+
+    Returns:
+        list[Image]: A list of images.
+    """
     data = get("/media/category/desktopWallpapers")
     return [Image.from_dict(item) for item in data]
 
 
 def get_mobile_wallpapers() -> list[Image]:
+    """Get mobile wallpapers from the media API.
+
+    Returns:
+        list[Image]: A list of images.
+    """
     data = get("/media/category/mobileWallpapers")
     return [Image.from_dict(item) for item in data]
 
 
 def get_concept_arts() -> list[Image]:
+    """Get concept arts from the media API.
+
+    Returns:
+        list[Image]: A list of images.
+    """
     data = get("/media/category/conceptArt")
     return [Image.from_dict(item) for item in data]
 
 
 def get_videos() -> list[Video]:
+    """Get videos from the media API.
+
+    Returns:
+        list[Video]: A list of videos.
+    """
     data = get("/media/category/videos")
     return [Video.from_dict(item) for item in data]

src/hytale/packages.py

@@ -3,6 +3,11 @@
 
 
 def get_packages() -> dict[str, Package]:
+    """Get all the current store packages.
+
+    Returns:
+        dict[str, Package]: A dictionary mapping package names to Package objects.
+    """
     data = get("/packages", "store.")
 
     for pkg_dict in data.values():

src/hytale/status.py

@@ -3,5 +3,10 @@
 
 
 def get_status() -> Status:
+    """Get the current status of the Hytale API.
+
+    Returns:
+        Status: The current status.
+    """
     data = get("/status")
     return Status(data)