universal-mcp-applications 0.1.22__py3-none-any.whl → 0.1.39rc8__py3-none-any.whl

universal_mcp/applications/reddit/app.py

@@ -1,5 +1,4 @@
 from typing import Any
-
 import httpx
 from loguru import logger
 from universal_mcp.applications.application import APIApplication
@@ -38,15 +37,9 @@ class RedditApp(APIApplication):
         if "access_token" not in credentials:
             logger.error("Reddit credentials found but missing 'access_token'.")
             raise ValueError("Invalid Reddit credentials format.")
+        return {"Authorization": f"Bearer {credentials['access_token']}", "User-Agent": "agentr-reddit-app/0.1 by AgentR"}
 
-        return {
-            "Authorization": f"Bearer {credentials['access_token']}",
-            "User-Agent": "agentr-reddit-app/0.1 by AgentR",
-        }
-
-    def get_subreddit_posts(
-        self, subreddit: str, limit: int = 5, timeframe: str = "day"
-    ) -> dict[str, Any]:
+    async def get_subreddit_posts(self, subreddit: str, limit: int = 5, timeframe: str = "day") -> dict[str, Any]:
         """
         Fetches a specified number of top-rated posts from a particular subreddit, allowing results to be filtered by a specific timeframe (e.g., 'day', 'week'). This is a simplified version compared to `get_subreddit_top_posts`, which uses more complex pagination parameters instead of a direct time filter.
 
@@ -56,7 +49,7 @@ class RedditApp(APIApplication):
             timeframe: The time period for top posts. Valid options: 'hour', 'day', 'week', 'month', 'year', 'all' (default: 'day')
 
         Returns:
-            A formatted string containing a numbered list of top posts, including titles, authors, scores, and URLs, or an error message if the request fails
+            A dictionary containing a list of top posts with their details, or an error message if the request fails.
 
         Raises:
             RequestException: When the HTTP request to the Reddit API fails
@@ -69,34 +62,29 @@ class RedditApp(APIApplication):
         if timeframe not in valid_timeframes:
             return f"Error: Invalid timeframe '{timeframe}'. Please use one of: {', '.join(valid_timeframes)}"
         if not 1 <= limit <= 100:
-            return (
-                f"Error: Invalid limit '{limit}'. Please use a value between 1 and 100."
-            )
+            return f"Error: Invalid limit '{limit}'. Please use a value between 1 and 100."
         url = f"{self.base_api_url}/r/{subreddit}/top"
         params = {"limit": limit, "t": timeframe}
-        logger.info(
-            f"Requesting top {limit} posts from r/{subreddit} for timeframe '{timeframe}'"
-        )
-        response = self._get(url, params=params)
+        logger.info(f"Requesting top {limit} posts from r/{subreddit} for timeframe '{timeframe}'")
+        response = await self._aget(url, params=params)
         return self._handle_response(response)
 
-    def search_subreddits(
-        self, query: str, limit: int = 5, sort: str = "relevance"
-    ) -> str:
+    async def search_subreddits(self, query: str, limit: int = 5, sort: str = "relevance") -> dict[str, Any]:
         """
-        Searches for subreddits by name and description using a query string, with results sortable by relevance or activity. Unlike the broader `search_reddit` function, this method exclusively discovers subreddits, not posts, comments, or users.
+        Finds subreddits based on a query string, searching their names and descriptions.
+        Results can be sorted by relevance or activity. This function is for discovering communities and does not search for posts or users, unlike the more general `search_reddit` function.
 
         Args:
-            query: The text to search for in subreddit names and descriptions
-            limit: The maximum number of subreddits to return, between 1 and 100 (default: 5)
-            sort: The order of results, either 'relevance' or 'activity' (default: 'relevance')
+            query: The search query for subreddit names and descriptions.
+            limit: The maximum number of subreddits to return (1-100, default is 5).
+            sort: The sorting order for results. Can be 'relevance' or 'activity' (default is 'relevance').
 
         Returns:
-            A formatted string containing a list of matching subreddits with their names, subscriber counts, and descriptions, or an error message if the search fails or parameters are invalid
+            A dictionary containing a list of matching subreddits, including their names, subscriber counts, and descriptions. Returns an error message on failure.
 
         Raises:
-            RequestException: When the HTTP request to Reddit's API fails
-            JSONDecodeError: When the API response contains invalid JSON
+            RequestException: If the API request to Reddit fails.
+            JSONDecodeError: If the API response is not valid JSON.
 
         Tags:
             search, important, reddit, api, query, format, list, validation
@@ -105,22 +93,14 @@ class RedditApp(APIApplication):
         if sort not in valid_sorts:
             return f"Error: Invalid sort option '{sort}'. Please use one of: {', '.join(valid_sorts)}"
         if not 1 <= limit <= 100:
-            return (
-                f"Error: Invalid limit '{limit}'. Please use a value between 1 and 100."
-            )
+            return f"Error: Invalid limit '{limit}'. Please use a value between 1 and 100."
         url = f"{self.base_api_url}/subreddits/search"
-        params = {
-            "q": query,
-            "limit": limit,
-            "sort": sort,
-        }
-        logger.info(
-            f"Searching for subreddits matching '{query}' (limit: {limit}, sort: {sort})"
-        )
-        response = self._get(url, params=params)
+        params = {"q": query, "limit": limit, "sort": sort}
+        logger.info(f"Searching for subreddits matching '{query}' (limit: {limit}, sort: {sort})")
+        response = await self._aget(url, params=params)
         return self._handle_response(response)
 
-    def get_post_flairs(self, subreddit: str):
+    async def get_post_flairs(self, subreddit: str):
         """
         Fetches a list of available post flairs (tags) for a specified subreddit. This is primarily used to discover the correct `flair_id` needed to categorize a new submission when using the `create_post` function. It returns flair details or a message if none are available.
 
@@ -139,21 +119,13 @@ class RedditApp(APIApplication):
         """
         url = f"{self.base_api_url}/r/{subreddit}/api/link_flair_v2"
         logger.info(f"Fetching post flairs for subreddit: r/{subreddit}")
-        response = self._get(url)
+        response = await self._aget(url)
         flairs = response.json()
         if not flairs:
             return f"No post flairs available for r/{subreddit}."
         return flairs
 
-    def create_post(
-        self,
-        subreddit: str,
-        title: str,
-        kind: str = "self",
-        text: str = None,
-        url: str = None,
-        flair_id: str = None,
-    ):
+    async def create_post(self, subreddit: str, title: str, kind: str = "self", text: str = None, url: str = None, flair_id: str = None):
         """
         Creates a new Reddit post in a specified subreddit. It supports text ('self') or link posts, requiring a title and corresponding content (text or URL). An optional flair can be assigned. Returns the API response or a formatted error message on failure.
 
@@ -176,37 +148,24 @@ class RedditApp(APIApplication):
         """
         if kind not in ["self", "link"]:
             raise ValueError("Invalid post kind. Must be one of 'self' or 'link'.")
-        if kind == "self" and not text:
+        if kind == "self" and (not text):
             raise ValueError("Text content is required for text posts.")
-        if kind == "link" and not url:
+        if kind == "link" and (not url):
             raise ValueError("URL is required for link posts (including images).")
-        data = {
-            "sr": subreddit,
-            "title": title,
-            "kind": kind,
-            "text": text,
-            "url": url,
-            "flair_id": flair_id,
-        }
+        data = {"sr": subreddit, "title": title, "kind": kind, "text": text, "url": url, "flair_id": flair_id}
         data = {k: v for k, v in data.items() if v is not None}
         url_api = f"{self.base_api_url}/api/submit"
         logger.info(f"Submitting a new post to r/{subreddit}")
-        response = self._post(url_api, data=data)
+        response = await self._apost(url_api, data=data)
         response_json = response.json()
-        if (
-            response_json
-            and "json" in response_json
-            and "errors" in response_json["json"]
-        ):
+        if response_json and "json" in response_json and ("errors" in response_json["json"]):
             errors = response_json["json"]["errors"]
             if errors:
-                error_message = ", ".join(
-                    [f"{code}: {message}" for code, message in errors]
-                )
+                error_message = ", ".join([f"{code}: {message}" for code, message in errors])
                 return f"Reddit API error: {error_message}"
         return response_json
 
-    def get_comment_by_id(self, comment_id: str) -> dict:
+    async def get_comment_by_id(self, comment_id: str) -> dict:
         """
         Retrieves a single Reddit comment's data, such as author and score, using its unique 't1_' prefixed ID. Unlike `get_post_comments_details` which fetches all comments for a post, this function targets one specific comment directly, returning an error dictionary if it is not found.
 
@@ -224,7 +183,7 @@ class RedditApp(APIApplication):
             retrieve, get, reddit, comment, api, fetch, single-item, important
         """
         url = f"https://oauth.reddit.com/api/info.json?id={comment_id}"
-        response = self._get(url)
+        response = await self._aget(url)
         data = response.json()
         comments = data.get("data", {}).get("children", [])
         if comments:
@@ -232,7 +191,7 @@ class RedditApp(APIApplication):
         else:
             return {"error": "Comment not found."}
 
-    def post_comment(self, parent_id: str, text: str) -> dict:
+    async def post_comment(self, parent_id: str, text: str) -> dict:
         """
         Posts a new comment as a reply to a specified Reddit post or another comment. Using the parent's full ID and the desired text, it submits the comment via the API and returns the response containing the new comment's details.
 
@@ -251,15 +210,12 @@ class RedditApp(APIApplication):
             post, comment, social, reddit, api, important
         """
         url = f"{self.base_api_url}/api/comment"
-        data = {
-            "parent": parent_id,
-            "text": text,
-        }
+        data = {"parent": parent_id, "text": text}
         logger.info(f"Posting comment to {parent_id}")
-        response = self._post(url, data=data)
+        response = await self._apost(url, data=data)
         return response.json()
 
-    def edit_content(self, content_id: str, text: str) -> dict:
+    async def edit_content(self, content_id: str, text: str) -> dict:
         """
         Modifies the text of a specific Reddit post or comment via its unique ID. Unlike creation or deletion functions, this method specifically handles updates to existing user-generated content, submitting the new text to the API and returning a JSON response detailing the edited item.
 
@@ -278,15 +234,12 @@ class RedditApp(APIApplication):
             edit, update, content, reddit, api, important
         """
         url = f"{self.base_api_url}/api/editusertext"
-        data = {
-            "thing_id": content_id,
-            "text": text,
-        }
+        data = {"thing_id": content_id, "text": text}
         logger.info(f"Editing content {content_id}")
-        response = self._post(url, data=data)
+        response = await self._apost(url, data=data)
         return response.json()
 
-    def delete_content(self, content_id: str) -> dict:
+    async def delete_content(self, content_id: str) -> dict:
         """
         Deletes a specified Reddit post or comment using its full identifier (`content_id`). It sends a POST request to the `/api/del` endpoint for permanent removal, unlike `edit_content` which only modifies. On success, it returns a confirmation message.
 
@@ -304,73 +257,64 @@ class RedditApp(APIApplication):
             delete, content-management, api, reddit, important
         """
         url = f"{self.base_api_url}/api/del"
-        data = {
-            "id": content_id,
-        }
+        data = {"id": content_id}
         logger.info(f"Deleting content {content_id}")
-        response = self._post(url, data=data)
+        response = await self._apost(url, data=data)
         response.raise_for_status()
         return {"message": f"Content {content_id} deleted successfully."}
 
-    def get_current_user_info(self) -> Any:
+    async def get_current_user_info(self) -> Any:
         """
         Retrieves the full profile information for the currently authenticated user by making a GET request to the `/api/v1/me` Reddit API endpoint. This differs from `get_user_profile`, which requires a username, and `get_current_user_karma`, which specifically fetches karma data.
 
         Returns:
-            Any: API response data.
+            A dictionary containing the authenticated user's profile information.
 
         Tags:
             users
         """
         url = f"{self.base_url}/api/v1/me"
         query_params = {}
-        response = self._get(url, params=query_params)
+        response = await self._aget(url, params=query_params)
         response.raise_for_status()
         return response.json()
 
-    def get_current_user_karma(self) -> Any:
+    async def get_current_user_karma(self) -> Any:
         """
         Fetches the karma breakdown for the authenticated user from the Reddit API. This function specifically targets the `/api/v1/me/karma` endpoint, returning karma statistics per subreddit, which is more specific than `get_current_user_info` that retrieves general profile information.
 
         Returns:
-            Any: API response data.
+            A dictionary containing the authenticated user's karma breakdown by subreddit.
 
         Tags:
             account
         """
         url = f"{self.base_url}/api/v1/me/karma"
         query_params = {}
-        response = self._get(url, params=query_params)
+        response = await self._aget(url, params=query_params)
         response.raise_for_status()
         return response.json()
 
-    def get_post_comments_details(self, post_id: str) -> Any:
+    async def get_post_comments_details(self, post_id: str) -> Any:
         """
         Fetches a specific Reddit post's details and its complete comment tree using the post's unique ID. This function returns the entire discussion, including the original post and all associated comments, providing broader context than `get_comment_by_id` which only retrieves a single comment.
 
         Args:
-            post_id (string): The Reddit post ID ( e.g. '1m734tx' for https://www.reddit.com/r/mcp/comments/1m734tx/comment/n4occ77/)
+            post_id (str): The Reddit post ID ( e.g. '1m734tx' for https://www.reddit.com/r/mcp/comments/1m734tx/comment/n4occ77/)
 
         Returns:
-            Any: API response data containing post details and comments.
+            A dictionary containing the post details and its comment tree.
 
         Tags:
             listings, comments, posts, important
         """
-
         url = f"{self.base_url}/comments/{post_id}.json"
         query_params = {}
-        response = self._get(url, params=query_params)
+        response = await self._aget(url, params=query_params)
         return self._handle_response(response)
 
-    def get_controversial_posts(
-        self,
-        after: str = None,
-        before: str = None,
-        count: int = None,
-        limit: int = None,
-        show: str = None,
-        sr_detail: str = None,
+    async def get_controversial_posts(
+        self, after: str = None, before: str = None, count: int = None, limit: int = None, show: str = None, sr_detail: str = None
     ) -> Any:
         """
         Fetches a global list of the most controversial posts from across all of Reddit, distinct from subreddit-specific queries. Optional parameters allow for pagination and customization of the results, returning the direct API response data with the post listings.
@@ -384,7 +328,7 @@ class RedditApp(APIApplication):
             sr_detail: Optional. Expand subreddit details.
 
         Returns:
-            Any: API response data containing a list of controversial posts.
+            A dictionary containing a listing of controversial posts.
 
         Tags:
             listings, posts, controversial, read-only
@@ -392,21 +336,14 @@ class RedditApp(APIApplication):
         url = f"{self.base_url}/controversial"
         query_params = {
             k: v
-            for k, v in [
-                ("after", after),
-                ("before", before),
-                ("count", count),
-                ("limit", limit),
-                ("show", show),
-                ("sr_detail", sr_detail),
-            ]
+            for k, v in [("after", after), ("before", before), ("count", count), ("limit", limit), ("show", show), ("sr_detail", sr_detail)]
             if v is not None
         }
-        response = self._get(url, params=query_params)
+        response = await self._aget(url, params=query_params)
         response.raise_for_status()
         return response.json()
 
-    def get_hot_posts(
+    async def get_hot_posts(
         self,
         g: str = None,
         after: str = None,
@@ -429,7 +366,7 @@ class RedditApp(APIApplication):
             sr_detail: Optional. Expand subreddit details.
 
         Returns:
-            Any: API response data containing a list of hot posts.
+            A dictionary containing a listing of hot posts.
 
         Tags:
             listings, posts, hot, read-only
@@ -448,18 +385,12 @@ class RedditApp(APIApplication):
             ]
             if v is not None
         }
-        response = self._get(url, params=query_params)
+        response = await self._aget(url, params=query_params)
         response.raise_for_status()
         return response.json()
 
-    def get_new_posts(
-        self,
-        after: str = None,
-        before: str = None,
-        count: int = None,
-        limit: int = None,
-        show: str = None,
-        sr_detail: str = None,
+    async def get_new_posts(
+        self, after: str = None, before: str = None, count: int = None, limit: int = None, show: str = None, sr_detail: str = None
     ) -> Any:
         """
         Fetches a list of the newest posts from across all of Reddit, not limited to a specific subreddit. This function supports optional pagination and filtering parameters to customize the API response, differentiating it from `get_subreddit_new_posts` which targets a single subreddit.
@@ -473,7 +404,7 @@ class RedditApp(APIApplication):
             sr_detail: Optional. Expand subreddit details.
 
         Returns:
-            Any: API response data containing a list of new posts.
+            A dictionary containing a listing of new posts.
 
         Tags:
             listings, posts, new, read-only
@@ -481,21 +412,14 @@ class RedditApp(APIApplication):
         url = f"{self.base_url}/new"
         query_params = {
             k: v
-            for k, v in [
-                ("after", after),
-                ("before", before),
-                ("count", count),
-                ("limit", limit),
-                ("show", show),
-                ("sr_detail", sr_detail),
-            ]
+            for k, v in [("after", after), ("before", before), ("count", count), ("limit", limit), ("show", show), ("sr_detail", sr_detail)]
             if v is not None
         }
-        response = self._get(url, params=query_params)
+        response = await self._aget(url, params=query_params)
         response.raise_for_status()
         return response.json()
 
-    def get_subreddit_hot_posts(
+    async def get_subreddit_hot_posts(
         self,
         subreddit: str,
         g: str = None,
@@ -520,7 +444,7 @@ class RedditApp(APIApplication):
             sr_detail: Optional. Expand subreddit details.
 
         Returns:
-            Any: API response data containing a list of hot posts from the subreddit.
+            A dictionary containing a listing of hot posts from the specified subreddit.
 
         Tags:
             listings, posts, subreddit, hot, read-only
@@ -541,11 +465,11 @@ class RedditApp(APIApplication):
             ]
             if v is not None
         }
-        response = self._get(url, params=query_params)
+        response = await self._aget(url, params=query_params)
         response.raise_for_status()
         return response.json()
 
-    def get_subreddit_new_posts(
+    async def get_subreddit_new_posts(
         self,
         subreddit: str,
         after: str = None,
@@ -568,7 +492,7 @@ class RedditApp(APIApplication):
             sr_detail: Optional. Expand subreddit details.
 
         Returns:
-            Any: API response data containing a list of new posts from the subreddit.
+            A dictionary containing a listing of new posts from the specified subreddit.
 
         Tags:
             listings, posts, subreddit, new, read-only
@@ -578,21 +502,14 @@ class RedditApp(APIApplication):
         url = f"{self.base_url}/r/{subreddit}/new"
         query_params = {
             k: v
-            for k, v in [
-                ("after", after),
-                ("before", before),
-                ("count", count),
-                ("limit", limit),
-                ("show", show),
-                ("sr_detail", sr_detail),
-            ]
+            for k, v in [("after", after), ("before", before), ("count", count), ("limit", limit), ("show", show), ("sr_detail", sr_detail)]
             if v is not None
         }
-        response = self._get(url, params=query_params)
+        response = await self._aget(url, params=query_params)
         response.raise_for_status()
         return response.json()
 
-    def get_subreddit_top_posts(
+    async def get_subreddit_top_posts(
         self,
         subreddit: str,
         after: str = None,
@@ -615,7 +532,7 @@ class RedditApp(APIApplication):
             sr_detail: Optional. Expand subreddit details.
 
         Returns:
-            Any: API response data containing a list of top posts from the subreddit.
+            A dictionary containing a listing of top posts from the specified subreddit.
 
         Tags:
             listings, posts, subreddit, top, read-only
@@ -625,28 +542,15 @@ class RedditApp(APIApplication):
         url = f"{self.base_url}/r/{subreddit}/top"
         query_params = {
             k: v
-            for k, v in [
-                ("after", after),
-                ("before", before),
-                ("count", count),
-                ("limit", limit),
-                ("show", show),
-                ("sr_detail", sr_detail),
-            ]
+            for k, v in [("after", after), ("before", before), ("count", count), ("limit", limit), ("show", show), ("sr_detail", sr_detail)]
             if v is not None
         }
-        response = self._get(url, params=query_params)
+        response = await self._aget(url, params=query_params)
         response.raise_for_status()
         return response.json()
 
-    def get_rising_posts(
-        self,
-        after: str = None,
-        before: str = None,
-        count: int = None,
-        limit: int = None,
-        show: str = None,
-        sr_detail: str = None,
+    async def get_rising_posts(
+        self, after: str = None, before: str = None, count: int = None, limit: int = None, show: str = None, sr_detail: str = None
     ) -> Any:
         """
         Retrieves a list of rising posts from across all of Reddit. Unlike subreddit-specific listing functions (e.g., `get_subreddit_hot_posts`), this operates globally. It supports optional pagination and filtering parameters, such as `limit` and `after`, to customize the API response and navigate through results.
@@ -660,7 +564,7 @@ class RedditApp(APIApplication):
             sr_detail: Optional. Expand subreddit details.
 
         Returns:
-            Any: API response data containing a list of rising posts.
+            A dictionary containing a listing of rising posts.
 
         Tags:
             listings, posts, rising, read-only
@@ -668,28 +572,15 @@ class RedditApp(APIApplication):
         url = f"{self.base_url}/rising"
         query_params = {
             k: v
-            for k, v in [
-                ("after", after),
-                ("before", before),
-                ("count", count),
-                ("limit", limit),
-                ("show", show),
-                ("sr_detail", sr_detail),
-            ]
+            for k, v in [("after", after), ("before", before), ("count", count), ("limit", limit), ("show", show), ("sr_detail", sr_detail)]
             if v is not None
         }
-        response = self._get(url, params=query_params)
+        response = await self._aget(url, params=query_params)
         response.raise_for_status()
         return response.json()
 
-    def get_top_posts(
-        self,
-        after: str = None,
-        before: str = None,
-        count: int = None,
-        limit: int = None,
-        show: str = None,
-        sr_detail: str = None,
+    async def get_top_posts(
+        self, after: str = None, before: str = None, count: int = None, limit: int = None, show: str = None, sr_detail: str = None
     ) -> Any:
         """
         Fetches top-rated posts from across all of Reddit, distinct from `get_subreddit_top_posts`, which operates on a specific subreddit. The function supports standard API pagination parameters like `limit`, `after`, and `before` to navigate results, providing a broad, site-wide view of top content.
@@ -703,7 +594,7 @@ class RedditApp(APIApplication):
             sr_detail: Optional. Expand subreddit details.
 
         Returns:
-            Any: API response data containing a list of top posts.
+            A dictionary containing a listing of top posts.
 
         Tags:
             listings, posts, top, read-only
@@ -711,21 +602,14 @@ class RedditApp(APIApplication):
         url = f"{self.base_url}/top"
         query_params = {
             k: v
-            for k, v in [
-                ("after", after),
-                ("before", before),
-                ("count", count),
-                ("limit", limit),
-                ("show", show),
-                ("sr_detail", sr_detail),
-            ]
+            for k, v in [("after", after), ("before", before), ("count", count), ("limit", limit), ("show", show), ("sr_detail", sr_detail)]
             if v is not None
         }
-        response = self._get(url, params=query_params)
+        response = await self._aget(url, params=query_params)
         response.raise_for_status()
         return response.json()
 
-    def search_reddit(
+    async def search_reddit(
         self,
         after: str = None,
         before: str = None,
@@ -760,7 +644,7 @@ class RedditApp(APIApplication):
             type: Optional. A comma-separated list of result types ('sr', 'link', 'user').
 
         Returns:
-            Any: API response data containing search results.
+            A dictionary containing the search results.
 
         Tags:
             search, reddit, posts, comments, users, read-only
@@ -785,11 +669,11 @@ class RedditApp(APIApplication):
             ]
             if v is not None
         }
-        response = self._get(url, params=query_params)
+        response = await self._aget(url, params=query_params)
         response.raise_for_status()
         return response.json()
 
-    def get_user_profile(self, username: str) -> Any:
+    async def get_user_profile(self, username: str) -> Any:
         """
         Retrieves public profile information for a specified Reddit user via the `/user/{username}/about` endpoint. Unlike `get_current_user_info`, which targets the authenticated user, this function fetches data like karma and account age for any user identified by their username.
 
@@ -806,7 +690,7 @@ class RedditApp(APIApplication):
             raise ValueError("Missing required parameter 'username'")
         url = f"{self.base_url}/user/{username}/about"
         query_params = {k: v for k, v in [("username", username)] if v is not None}
-        response = self._get(url, params=query_params)
+        response = await self._aget(url, params=query_params)
         response.raise_for_status()
         return response.json()