diff --git a/.codeboarding/Configuration_Manager.json b/.codeboarding/Configuration_Manager.json new file mode 100644 index 000000000..90a52a5c6 --- /dev/null +++ b/.codeboarding/Configuration_Manager.json @@ -0,0 +1,41 @@ +{ + "description": "The PRAW library's core architecture is centered around two main components: the Configuration Manager and the Reddit API Client. The Configuration Manager, implemented by the praw.config.Config class, is responsible for abstracting and providing all necessary configuration settings, such as API credentials and user agent information, which can be sourced from praw.ini files or environment variables. This ensures a flexible and centralized approach to managing application settings. The Reddit API Client, represented by the praw.Reddit.Reddit class, serves as the primary interface for interacting with the Reddit API. It critically depends on the Configuration Manager to obtain its initialization parameters, enabling it to establish authenticated sessions and facilitate all subsequent API requests. This clear separation of concerns allows for robust configuration handling and a streamlined API interaction experience.", + "components": [ + { + "name": "Configuration Manager", + "description": "This component is responsible for centralizing the loading, parsing, and provision of PRAW's configuration settings. It abstracts the underlying storage mechanisms (e.g., praw.ini file, environment variables) and offers a unified interface for retrieving critical API access parameters such as client ID, client secret, user agent, and redirect URI. These parameters are fundamental for establishing a connection and authenticating with the Reddit API.", + "referenced_source_code": [ + { + "qualified_name": "praw.config.Config", + "reference_file": "praw/config.py", + "reference_start_line": 52, + "reference_end_line": 52 + } + ] + }, + { + "name": "Reddit API Client", + "description": "As the main API client, this component serves as the primary interface for all interactions with the Reddit API. It requires the configuration parameters managed by the Configuration Manager to initialize itself, authenticate, and make requests. It acts as the entry point for developers to access various Reddit resources and functionalities.", + "referenced_source_code": [ + { + "qualified_name": "praw.Reddit.Reddit", + "reference_file": "praw/reddit.py", + "reference_start_line": 57, + "reference_end_line": 901 + } + ] + }, + { + "name": "Unclassified", + "description": "Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies)", + "referenced_source_code": [] + } + ], + "components_relations": [ + { + "relation": "provides configuration to", + "src_name": "Configuration Manager", + "dst_name": "Reddit API Client" + } + ] +} diff --git a/.codeboarding/Configuration_Manager.rst b/.codeboarding/Configuration_Manager.rst new file mode 100644 index 000000000..edd120c59 --- /dev/null +++ b/.codeboarding/Configuration_Manager.rst @@ -0,0 +1,52 @@ +Configuration Manager +===================== + +.. mermaid:: + + graph LR + Configuration_Manager["Configuration Manager"] + Reddit_API_Client["Reddit API Client"] + Unclassified["Unclassified"] + Configuration_Manager -- "provides configuration to" --> Reddit_API_Client + click Configuration_Manager href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Configuration_Manager.html" "Details" + +| |codeboarding-badge| |demo-badge| |contact-badge| + +.. |codeboarding-badge| image:: https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square + :target: https://github.com/CodeBoarding/CodeBoarding +.. |demo-badge| image:: https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square + :target: https://www.codeboarding.org/demo +.. |contact-badge| image:: https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square + :target: mailto:contact@codeboarding.org + +Details +------- + +The PRAW library's core architecture is centered around two main components: the Configuration Manager and the Reddit API Client. The Configuration Manager, implemented by the praw.config.Config class, is responsible for abstracting and providing all necessary configuration settings, such as API credentials and user agent information, which can be sourced from praw.ini files or environment variables. This ensures a flexible and centralized approach to managing application settings. The Reddit API Client, represented by the praw.Reddit.Reddit class, serves as the primary interface for interacting with the Reddit API. It critically depends on the Configuration Manager to obtain its initialization parameters, enabling it to establish authenticated sessions and facilitate all subsequent API requests. This clear separation of concerns allows for robust configuration handling and a streamlined API interaction experience. + +Configuration Manager +^^^^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +This component is responsible for centralizing the loading, parsing, and provision of PRAW's configuration settings. It abstracts the underlying storage mechanisms (e.g., praw.ini file, environment variables) and offers a unified interface for retrieving critical API access parameters such as client ID, client secret, user agent, and redirect URI. These parameters are fundamental for establishing a connection and authenticating with the Reddit API. + +**Related Classes/Methods**: + +* praw.config.Config + +Reddit API Client +^^^^^^^^^^^^^^^^^ + +As the main API client, this component serves as the primary interface for all interactions with the Reddit API. It requires the configuration parameters managed by the Configuration Manager to initialize itself, authenticate, and make requests. It acts as the entry point for developers to access various Reddit resources and functionalities. + +**Related Classes/Methods**: + +* praw.Reddit.Reddit:57-901 + +Unclassified +^^^^^^^^^^^^ + +Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies) + +**Related Classes/Methods**: *None* diff --git a/.codeboarding/Listing_Streaming.json b/.codeboarding/Listing_Streaming.json new file mode 100644 index 000000000..0918a2a22 --- /dev/null +++ b/.codeboarding/Listing_Streaming.json @@ -0,0 +1,143 @@ +{ + "description": "The PRAW library's data retrieval architecture is primarily composed of two distinct but complementary patterns: listing generation and stream generation. The ListingGenerator forms the backbone for paginated data retrieval, efficiently fetching and iterating through large datasets from the Reddit API. This core functionality is extended and specialized by BaseListingMixin, SubredditListingMixin, and RedditorListingMixin, which provide context-specific listing capabilities for general, subreddit, and redditor content, respectively. For real-time data, the StreamGenerator (implemented as stream_generator utility) offers a robust mechanism for continuous data delivery, handling deduplication and rate limiting. This utility is leveraged by higher-level stream methods within Redditors, Inbox, and Subreddits classes, providing user-friendly entry points for accessing live streams of redditors, inbox messages, and subreddit content. This dual approach ensures comprehensive and efficient access to both historical and real-time Reddit data.", + "components": [ + { + "name": "ListingGenerator", + "description": "Manages the iteration and pagination of items from Reddit API responses. It handles fetching data in batches, extracting relevant sub-lists, and providing an iterable interface to the user, abstracting away pagination details. This component is crucial for efficiently handling large datasets from the Reddit API.", + "referenced_source_code": [ + { + "qualified_name": "ListingGenerator", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py", + "reference_start_line": 17, + "reference_end_line": 103 + } + ] + }, + { + "name": "BaseListingMixin", + "description": "Provides foundational listing methods such as `hot`, `new`, `top`, and `controversial`. It prepares generic API requests and validates time filters applicable across various Reddit resources, serving as a common interface for listing operations.", + "referenced_source_code": [ + { + "qualified_name": "BaseListingMixin", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/mixins/base.py", + "reference_start_line": 15, + "reference_end_line": 149 + } + ] + }, + { + "name": "SubredditListingMixin", + "description": "Specializes listing functionality for subreddit-specific content, including comments and submissions within a subreddit. It determines appropriate API paths for subreddit-related data, extending the base listing capabilities.", + "referenced_source_code": [ + { + "qualified_name": "SubredditListingMixin", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/mixins/subreddit.py", + "reference_start_line": 49, + "reference_end_line": 73 + } + ] + }, + { + "name": "RedditorListingMixin", + "description": "Specializes listing functionality for redditor-specific content, such as comments and submissions made by a particular user. It creates sub-listings tailored to user activity, providing a user-centric view of Reddit data.", + "referenced_source_code": [ + { + "qualified_name": "RedditorListingMixin", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/mixins/redditor.py", + "reference_start_line": 35, + "reference_end_line": 185 + } + ] + }, + { + "name": "StreamGenerator", + "description": "This component, implemented as the `stream_generator` function, provides a generic, low-level mechanism for continuously yielding new items from a source. It manages the stream's state, handles deduplication using a `BoundedSet`, and incorporates exponential backoff for rate limiting, forming the core engine for all streaming operations. This is the fundamental utility for real-time data.", + "referenced_source_code": [ + { + "qualified_name": "stream_generator", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/util.py", + "reference_start_line": 36, + "reference_end_line": 163 + } + ] + }, + { + "name": "RedditorsStream", + "description": "Represents the `stream` method within the `Redditors` class, acting as an entry point for initiating and managing a continuous stream of new redditors as they are created or become active. It provides a high-level interface for accessing real-time user data by leveraging the `stream_generator` utility.", + "referenced_source_code": [ + { + "qualified_name": "Redditors.stream", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/redditors.py", + "reference_start_line": 93, + "reference_end_line": 104 + } + ] + }, + { + "name": "InboxStream", + "description": "Represents the `stream` method within the `Inbox` class, acting as an entry point for initiating and managing a continuous stream of unread inbox messages for the authenticated user. This component is vital for real-time notification and interaction features, leveraging the `stream_generator` utility.", + "referenced_source_code": [ + { + "qualified_name": "Inbox.stream", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/inbox.py", + "reference_start_line": 229, + "reference_end_line": 247 + } + ] + }, + { + "name": "SubredditContentStream", + "description": "Represents the `stream` method within the `Subreddits` class, providing access to streams of content related to a specific subreddit, including specialized moderation streams. This allows for real-time monitoring of activity within a subreddit by leveraging the `stream_generator` utility.", + "referenced_source_code": [ + { + "qualified_name": "Subreddits.stream", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/subreddits.py", + "reference_start_line": 124, + "reference_end_line": 133 + } + ] + } + ], + "components_relations": [ + { + "relation": "specializes", + "src_name": "SubredditListingMixin", + "dst_name": "BaseListingMixin" + }, + { + "relation": "specializes", + "src_name": "RedditorListingMixin", + "dst_name": "BaseListingMixin" + }, + { + "relation": "utilizes", + "src_name": "BaseListingMixin", + "dst_name": "ListingGenerator" + }, + { + "relation": "utilizes", + "src_name": "SubredditListingMixin", + "dst_name": "ListingGenerator" + }, + { + "relation": "utilizes", + "src_name": "RedditorListingMixin", + "dst_name": "ListingGenerator" + }, + { + "relation": "leverages", + "src_name": "RedditorsStream", + "dst_name": "StreamGenerator" + }, + { + "relation": "leverages", + "src_name": "InboxStream", + "dst_name": "StreamGenerator" + }, + { + "relation": "leverages", + "src_name": "SubredditContentStream", + "dst_name": "StreamGenerator" + } + ] +} diff --git a/.codeboarding/Listing_Streaming.rst b/.codeboarding/Listing_Streaming.rst new file mode 100644 index 000000000..ff41e468c --- /dev/null +++ b/.codeboarding/Listing_Streaming.rst @@ -0,0 +1,108 @@ +Listing Streaming +================= + +.. mermaid:: + + graph LR + ListingGenerator["ListingGenerator"] + BaseListingMixin["BaseListingMixin"] + SubredditListingMixin["SubredditListingMixin"] + RedditorListingMixin["RedditorListingMixin"] + StreamGenerator["StreamGenerator"] + RedditorsStream["RedditorsStream"] + InboxStream["InboxStream"] + SubredditContentStream["SubredditContentStream"] + SubredditListingMixin -- "specializes" --> BaseListingMixin + RedditorListingMixin -- "specializes" --> BaseListingMixin + BaseListingMixin -- "utilizes" --> ListingGenerator + SubredditListingMixin -- "utilizes" --> ListingGenerator + RedditorListingMixin -- "utilizes" --> ListingGenerator + RedditorsStream -- "leverages" --> StreamGenerator + InboxStream -- "leverages" --> StreamGenerator + SubredditContentStream -- "leverages" --> StreamGenerator + +| |codeboarding-badge| |demo-badge| |contact-badge| + +.. |codeboarding-badge| image:: https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square + :target: https://github.com/CodeBoarding/CodeBoarding +.. |demo-badge| image:: https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square + :target: https://www.codeboarding.org/demo +.. |contact-badge| image:: https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square + :target: mailto:contact@codeboarding.org + +Details +------- + +The PRAW library's data retrieval architecture is primarily composed of two distinct but complementary patterns: listing generation and stream generation. The ListingGenerator forms the backbone for paginated data retrieval, efficiently fetching and iterating through large datasets from the Reddit API. This core functionality is extended and specialized by BaseListingMixin, SubredditListingMixin, and RedditorListingMixin, which provide context-specific listing capabilities for general, subreddit, and redditor content, respectively. For real-time data, the StreamGenerator (implemented as stream_generator utility) offers a robust mechanism for continuous data delivery, handling deduplication and rate limiting. This utility is leveraged by higher-level stream methods within Redditors, Inbox, and Subreddits classes, providing user-friendly entry points for accessing live streams of redditors, inbox messages, and subreddit content. This dual approach ensures comprehensive and efficient access to both historical and real-time Reddit data. + +ListingGenerator +^^^^^^^^^^^^^^^^ + +Manages the iteration and pagination of items from Reddit API responses. It handles fetching data in batches, extracting relevant sub-lists, and providing an iterable interface to the user, abstracting away pagination details. This component is crucial for efficiently handling large datasets from the Reddit API. + +**Related Classes/Methods**: + +* `ListingGenerator:17-103 `_ + +BaseListingMixin +^^^^^^^^^^^^^^^^ + +Provides foundational listing methods such as `hot`, `new`, `top`, and `controversial`. It prepares generic API requests and validates time filters applicable across various Reddit resources, serving as a common interface for listing operations. + +**Related Classes/Methods**: + +* `BaseListingMixin:15-149 `_ + +SubredditListingMixin +^^^^^^^^^^^^^^^^^^^^^ + +Specializes listing functionality for subreddit-specific content, including comments and submissions within a subreddit. It determines appropriate API paths for subreddit-related data, extending the base listing capabilities. + +**Related Classes/Methods**: + +* `SubredditListingMixin:49-73 `_ + +RedditorListingMixin +^^^^^^^^^^^^^^^^^^^^ + +Specializes listing functionality for redditor-specific content, such as comments and submissions made by a particular user. It creates sub-listings tailored to user activity, providing a user-centric view of Reddit data. + +**Related Classes/Methods**: + +* `RedditorListingMixin:35-185 `_ + +StreamGenerator +^^^^^^^^^^^^^^^ + +This component, implemented as the `stream_generator` function, provides a generic, low-level mechanism for continuously yielding new items from a source. It manages the stream's state, handles deduplication using a `BoundedSet`, and incorporates exponential backoff for rate limiting, forming the core engine for all streaming operations. This is the fundamental utility for real-time data. + +**Related Classes/Methods**: + +* `stream_generator:36-163 `_ + +RedditorsStream +^^^^^^^^^^^^^^^ + +Represents the `stream` method within the `Redditors` class, acting as an entry point for initiating and managing a continuous stream of new redditors as they are created or become active. It provides a high-level interface for accessing real-time user data by leveraging the `stream_generator` utility. + +**Related Classes/Methods**: + +* `Redditors.stream:93-104 `_ + +InboxStream +^^^^^^^^^^^ + +Represents the `stream` method within the `Inbox` class, acting as an entry point for initiating and managing a continuous stream of unread inbox messages for the authenticated user. This component is vital for real-time notification and interaction features, leveraging the `stream_generator` utility. + +**Related Classes/Methods**: + +* `Inbox.stream:229-247 `_ + +SubredditContentStream +^^^^^^^^^^^^^^^^^^^^^^ + +Represents the `stream` method within the `Subreddits` class, providing access to streams of content related to a specific subreddit, including specialized moderation streams. This allows for real-time monitoring of activity within a subreddit by leveraging the `stream_generator` utility. + +**Related Classes/Methods**: + +* `Subreddits.stream:124-133 `_ diff --git a/.codeboarding/Low_Level_API_Connector.json b/.codeboarding/Low_Level_API_Connector.json new file mode 100644 index 000000000..67d70518b --- /dev/null +++ b/.codeboarding/Low_Level_API_Connector.json @@ -0,0 +1,118 @@ +{ + "description": "The `praw` library provides a high-level, Pythonic interface for interacting with the Reddit API. At its core, the `Reddit Client` acts as the primary orchestrator, managing user requests and coordinating with other internal components. It leverages an `Authentication Module` to handle various OAuth2 flows and token management, ensuring secure access to Reddit resources. `Configuration Management` centralizes the loading and parsing of settings, making the client adaptable to different environments. All interactions with Reddit's data are facilitated through `Data Models/Objects`, which abstract API responses into intuitive Python objects. For the actual network communication and low-level OAuth2 intricacies, `praw` relies on the `Low-Level API Connector` (prawcore), an external dependency that handles the complexities of HTTP requests and responses, thereby decoupling `praw` from the underlying network layer.", + "components": [ + { + "name": "Reddit Client", + "description": "The primary entry point for users to interact with the Reddit API. It orchestrates calls to other components to fulfill user requests, providing a high-level, Pythonic interface to Reddit resources.", + "referenced_source_code": [ + { + "qualified_name": "praw.Reddit", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 1, + "reference_end_line": 1 + } + ] + }, + { + "name": "Low-Level API Connector", + "description": "An external dependency, `prawcore`, which is solely responsible for handling the low-level HTTP communication with the Reddit API. It manages the actual network requests, responses, and the intricacies of OAuth2 authentication flows, abstracting these complexities from the higher-level `praw` library.", + "referenced_source_code": [ + { + "qualified_name": "prawcore", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 527, + "reference_end_line": 546 + } + ] + }, + { + "name": "Authentication Module", + "description": "Manages the various OAuth2 authentication flows (e.g., script, installed app, web app) and handles the storage and refreshing of access tokens.", + "referenced_source_code": [ + { + "qualified_name": "praw.auth", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/auth.py", + "reference_start_line": 1, + "reference_end_line": 1 + } + ] + }, + { + "name": "Data Models/Objects", + "description": "Represents Reddit API resources (e.g., `Submission`, `Comment`, `Subreddit`, `User`) as Python objects, providing attribute access and methods for interaction.", + "referenced_source_code": [ + { + "qualified_name": "praw.models.submission.Submission", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/submission.py", + "reference_start_line": 1, + "reference_end_line": 1 + }, + { + "qualified_name": "praw.models.subreddit.Subreddit", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/subreddit.py", + "reference_start_line": 1, + "reference_end_line": 1 + } + ] + }, + { + "name": "Configuration Management", + "description": "Handles the loading, parsing, and management of configuration settings (e.g., client ID, client secret, user agent) from various sources (e.g., `praw.ini`, environment variables).", + "referenced_source_code": [ + { + "qualified_name": "praw.config", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/config.py", + "reference_start_line": 1, + "reference_end_line": 1 + } + ] + } + ], + "components_relations": [ + { + "relation": "utilizes", + "src_name": "Reddit Client", + "dst_name": "Low-Level API Connector" + }, + { + "relation": "depends on", + "src_name": "Reddit Client", + "dst_name": "Low-Level API Connector" + }, + { + "relation": "configures", + "src_name": "Authentication Module", + "dst_name": "Low-Level API Connector" + }, + { + "relation": "provides authentication context to", + "src_name": "Authentication Module", + "dst_name": "Low-Level API Connector" + }, + { + "relation": "interacts with", + "src_name": "Reddit Client", + "dst_name": "Authentication Module" + }, + { + "relation": "uses", + "src_name": "Reddit Client", + "dst_name": "Data Models/Objects" + }, + { + "relation": "loads settings via", + "src_name": "Reddit Client", + "dst_name": "Configuration Management" + }, + { + "relation": "are populated by", + "src_name": "Data Models/Objects", + "dst_name": "Low-Level API Connector" + }, + { + "relation": "reads settings from", + "src_name": "Authentication Module", + "dst_name": "Configuration Management" + } + ] +} diff --git a/.codeboarding/Low_Level_API_Connector.rst b/.codeboarding/Low_Level_API_Connector.rst new file mode 100644 index 000000000..62dcdc029 --- /dev/null +++ b/.codeboarding/Low_Level_API_Connector.rst @@ -0,0 +1,86 @@ +Low Level Api Connector +======================= + +.. mermaid:: + + graph LR + Reddit_Client["Reddit Client"] + Low_Level_API_Connector["Low-Level API Connector"] + Authentication_Module["Authentication Module"] + Data_Models_Objects["Data Models/Objects"] + Configuration_Management["Configuration Management"] + Reddit_Client -- "utilizes" --> Low_Level_API_Connector + Reddit_Client -- "depends on" --> Low_Level_API_Connector + Authentication_Module -- "configures" --> Low_Level_API_Connector + Authentication_Module -- "provides authentication context to" --> Low_Level_API_Connector + Reddit_Client -- "interacts with" --> Authentication_Module + Reddit_Client -- "uses" --> Data_Models_Objects + Reddit_Client -- "loads settings via" --> Configuration_Management + Data_Models_Objects -- "are populated by" --> Low_Level_API_Connector + Authentication_Module -- "reads settings from" --> Configuration_Management + click Reddit_Client href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Reddit_Client.html" "Details" + click Low_Level_API_Connector href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Low_Level_API_Connector.html" "Details" + +| |codeboarding-badge| |demo-badge| |contact-badge| + +.. |codeboarding-badge| image:: https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square + :target: https://github.com/CodeBoarding/CodeBoarding +.. |demo-badge| image:: https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square + :target: https://www.codeboarding.org/demo +.. |contact-badge| image:: https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square + :target: mailto:contact@codeboarding.org + +Details +------- + +The `praw` library provides a high-level, Pythonic interface for interacting with the Reddit API. At its core, the `Reddit Client` acts as the primary orchestrator, managing user requests and coordinating with other internal components. It leverages an `Authentication Module` to handle various OAuth2 flows and token management, ensuring secure access to Reddit resources. `Configuration Management` centralizes the loading and parsing of settings, making the client adaptable to different environments. All interactions with Reddit's data are facilitated through `Data Models/Objects`, which abstract API responses into intuitive Python objects. For the actual network communication and low-level OAuth2 intricacies, `praw` relies on the `Low-Level API Connector` (prawcore), an external dependency that handles the complexities of HTTP requests and responses, thereby decoupling `praw` from the underlying network layer. + +Reddit Client +^^^^^^^^^^^^^ + +:ref:`Expand ` + +The primary entry point for users to interact with the Reddit API. It orchestrates calls to other components to fulfill user requests, providing a high-level, Pythonic interface to Reddit resources. + +**Related Classes/Methods**: + +* `praw.Reddit `_ + +Low-Level API Connector +^^^^^^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +An external dependency, `prawcore`, which is solely responsible for handling the low-level HTTP communication with the Reddit API. It manages the actual network requests, responses, and the intricacies of OAuth2 authentication flows, abstracting these complexities from the higher-level `praw` library. + +**Related Classes/Methods**: + +* `prawcore:527-546 `_ + +Authentication Module +^^^^^^^^^^^^^^^^^^^^^ + +Manages the various OAuth2 authentication flows (e.g., script, installed app, web app) and handles the storage and refreshing of access tokens. + +**Related Classes/Methods**: + +* `praw.auth `_ + +Data Models/Objects +^^^^^^^^^^^^^^^^^^^ + +Represents Reddit API resources (e.g., `Submission`, `Comment`, `Subreddit`, `User`) as Python objects, providing attribute access and methods for interaction. + +**Related Classes/Methods**: + +* `praw.models.submission.Submission `_ +* `praw.models.subreddit.Subreddit `_ + +Configuration Management +^^^^^^^^^^^^^^^^^^^^^^^^ + +Handles the loading, parsing, and management of configuration settings (e.g., client ID, client secret, user agent) from various sources (e.g., `praw.ini`, environment variables). + +**Related Classes/Methods**: + +* `praw.config `_ diff --git a/.codeboarding/Object_Transformer.json b/.codeboarding/Object_Transformer.json new file mode 100644 index 000000000..d0d459b3b --- /dev/null +++ b/.codeboarding/Object_Transformer.json @@ -0,0 +1,102 @@ +{ + "description": "The `Object Transformer` subsystem is primarily defined by the `praw.objector` module, specifically the `Objector` class and its associated methods. Its core responsibility is to convert raw JSON data received from the Reddit API into structured, type-safe PRAW Python objects, while also handling API-specific error detection and parsing.", + "components": [ + { + "name": "Objector Class", + "description": "Acts as the central facade and orchestrator for the entire objectification process. It manages the conversion of various raw data types (dictionaries, lists, booleans, etc.) into their corresponding PRAW objects and integrates error checking.", + "referenced_source_code": [ + { + "qualified_name": "praw.objector.Objector", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py", + "reference_start_line": 17, + "reference_end_line": 263 + } + ] + }, + { + "name": "Objector.objectify Method", + "description": "Serves as the main public entry point for initiating the transformation of raw data. It intelligently handles different input types (e.g., `None`, `list`, `bool`, `dict`) and directs the flow to appropriate internal methods, including an initial check for embedded API errors.", + "referenced_source_code": [ + { + "qualified_name": "praw.objector.Objector:objectify", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py", + "reference_start_line": 1, + "reference_end_line": 1 + } + ] + }, + { + "name": "Objector._objectify_dict Method", + "description": "Specializes in converting dictionary-structured data, which is typical for Reddit API responses, into specific PRAW objects. It contains conditional logic to identify the precise type of Reddit object (e.g., `ModmailConversation`, `Subreddit`, `Redditor`) based on key fields and applies the relevant parsing logic.", + "referenced_source_code": [ + { + "qualified_name": "praw.objector.Objector:_objectify_dict", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py", + "reference_start_line": 1, + "reference_end_line": 1 + } + ] + }, + { + "name": "Objector.check_error Method", + "description": "Examines the raw input data to determine if it represents an API error response. If an error is detected, it triggers the raising of a `RedditAPIException`, ensuring that API-level issues are properly surfaced.", + "referenced_source_code": [ + { + "qualified_name": "praw.objector.Objector:check_error", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py", + "reference_start_line": 1, + "reference_end_line": 1 + } + ] + }, + { + "name": "Objector.parse_error Method", + "description": "Extracts and formats detailed error messages from the raw API response, converting them into a structured `RedditAPIException` instance. This provides clear and actionable error information to the user.", + "referenced_source_code": [ + { + "qualified_name": "praw.objector.Objector:parse_error", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py", + "reference_start_line": 1, + "reference_end_line": 1 + } + ] + } + ], + "components_relations": [ + { + "relation": "orchestrates", + "src_name": "Objector Class", + "dst_name": "Objector.objectify Method" + }, + { + "relation": "orchestrates", + "src_name": "Objector Class", + "dst_name": "Objector._objectify_dict Method" + }, + { + "relation": "orchestrates", + "src_name": "Objector Class", + "dst_name": "Objector.check_error Method" + }, + { + "relation": "orchestrates", + "src_name": "Objector Class", + "dst_name": "Objector.parse_error Method" + }, + { + "relation": "delegates to", + "src_name": "Objector.objectify Method", + "dst_name": "Objector._objectify_dict Method" + }, + { + "relation": "invokes", + "src_name": "Objector.objectify Method", + "dst_name": "Objector.check_error Method" + }, + { + "relation": "calls", + "src_name": "Objector.check_error Method", + "dst_name": "Objector.parse_error Method" + } + ] +} diff --git a/.codeboarding/Object_Transformer.rst b/.codeboarding/Object_Transformer.rst new file mode 100644 index 000000000..0da8a3e3a --- /dev/null +++ b/.codeboarding/Object_Transformer.rst @@ -0,0 +1,77 @@ +Object Transformer +================== + +.. mermaid:: + + graph LR + Objector_Class["Objector Class"] + Objector_objectify_Method["Objector.objectify Method"] + Objector__objectify_dict_Method["Objector._objectify_dict Method"] + Objector_check_error_Method["Objector.check_error Method"] + Objector_parse_error_Method["Objector.parse_error Method"] + Objector_Class -- "orchestrates" --> Objector_objectify_Method + Objector_Class -- "orchestrates" --> Objector__objectify_dict_Method + Objector_Class -- "orchestrates" --> Objector_check_error_Method + Objector_Class -- "orchestrates" --> Objector_parse_error_Method + Objector_objectify_Method -- "delegates to" --> Objector__objectify_dict_Method + Objector_objectify_Method -- "invokes" --> Objector_check_error_Method + Objector_check_error_Method -- "calls" --> Objector_parse_error_Method + +| |codeboarding-badge| |demo-badge| |contact-badge| + +.. |codeboarding-badge| image:: https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square + :target: https://github.com/CodeBoarding/CodeBoarding +.. |demo-badge| image:: https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square + :target: https://www.codeboarding.org/demo +.. |contact-badge| image:: https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square + :target: mailto:contact@codeboarding.org + +Details +------- + +The `Object Transformer` subsystem is primarily defined by the `praw.objector` module, specifically the `Objector` class and its associated methods. Its core responsibility is to convert raw JSON data received from the Reddit API into structured, type-safe PRAW Python objects, while also handling API-specific error detection and parsing. + +Objector Class +^^^^^^^^^^^^^^ + +Acts as the central facade and orchestrator for the entire objectification process. It manages the conversion of various raw data types (dictionaries, lists, booleans, etc.) into their corresponding PRAW objects and integrates error checking. + +**Related Classes/Methods**: + +* `praw.objector.Objector:17-263 `_ + +Objector.objectify Method +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Serves as the main public entry point for initiating the transformation of raw data. It intelligently handles different input types (e.g., `None`, `list`, `bool`, `dict`) and directs the flow to appropriate internal methods, including an initial check for embedded API errors. + +**Related Classes/Methods**: + +* `praw.objector.Objector:objectify `_ + +Objector._objectify_dict Method +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Specializes in converting dictionary-structured data, which is typical for Reddit API responses, into specific PRAW objects. It contains conditional logic to identify the precise type of Reddit object (e.g., `ModmailConversation`, `Subreddit`, `Redditor`) based on key fields and applies the relevant parsing logic. + +**Related Classes/Methods**: + +* `praw.objector.Objector:_objectify_dict `_ + +Objector.check_error Method +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Examines the raw input data to determine if it represents an API error response. If an error is detected, it triggers the raising of a `RedditAPIException`, ensuring that API-level issues are properly surfaced. + +**Related Classes/Methods**: + +* `praw.objector.Objector:check_error `_ + +Objector.parse_error Method +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Extracts and formats detailed error messages from the raw API response, converting them into a structured `RedditAPIException` instance. This provides clear and actionable error information to the user. + +**Related Classes/Methods**: + +* `praw.objector.Objector:parse_error `_ diff --git a/.codeboarding/Reddit_Client.json b/.codeboarding/Reddit_Client.json new file mode 100644 index 000000000..65b561776 --- /dev/null +++ b/.codeboarding/Reddit_Client.json @@ -0,0 +1,224 @@ +{ + "description": "The PRAW library's core architecture is centered around the `Reddit API Client`, which serves as the primary interface and orchestrator. This client initializes and manages key components such as the `Authentication Manager`, `HTTP Request Dispatcher`, `Response Object Mapper`, and `Rate Limiting Handler`. User interactions primarily occur through `Resource Accessors`, which expose Pythonic methods for Reddit resources. These accessors delegate API requests to the `HTTP Request Dispatcher`, which handles the actual communication with the Reddit API, incorporating authentication via the `Authentication Manager` and adhering to rate limits managed by the `Rate Limiting Handler`. Raw API responses are then processed by the `Response Object Mapper`, transforming them into structured Python objects before being returned to the `Resource Accessors` for application logic. This design ensures a clear separation of concerns, from API interaction to data transformation and resource management.", + "components": [ + { + "name": "Reddit API Client", + "description": "The primary entry point and orchestrator for the entire PRAW library. It initializes and manages the lifecycle of other core components, providing a unified, high-level interface for accessing various Reddit resources.", + "referenced_source_code": [ + { + "qualified_name": "praw.reddit.Reddit", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 57, + "reference_end_line": 901 + } + ] + }, + { + "name": "Authentication Manager", + "description": "Handles the setup and management of authentication with the Reddit API, supporting different OAuth flows and credential management. It configures the underlying HTTP client for authenticated requests.", + "referenced_source_code": [ + { + "qualified_name": "praw.reddit.Reddit:_prepare_prawcore", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 0, + "reference_end_line": 0 + }, + { + "qualified_name": "praw.reddit.Reddit:_prepare_untrusted_prawcore", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 0, + "reference_end_line": 0 + }, + { + "qualified_name": "praw.reddit.Reddit:_prepare_trusted_prawcore", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 0, + "reference_end_line": 0 + }, + { + "qualified_name": "praw.reddit.Reddit:_prepare_common_authorizer", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 0, + "reference_end_line": 0 + } + ] + }, + { + "name": "HTTP Request Dispatcher", + "description": "Manages the end-to-end process of sending API requests. This includes preparing the request, dispatching it to the Reddit API, and handling the raw HTTP response. It integrates with the Rate Limiting Handler and may manage asynchronous operations.", + "referenced_source_code": [ + { + "qualified_name": "praw.reddit.Reddit:_objectify_request", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 0, + "reference_end_line": 0 + }, + { + "qualified_name": "praw.reddit.Reddit:request", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 0, + "reference_end_line": 0 + }, + { + "qualified_name": "praw.reddit.Reddit:_check_for_async", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 0, + "reference_end_line": 0 + } + ] + }, + { + "name": "Response Object Mapper", + "description": "Transforms raw JSON responses received from the Reddit API into structured and usable Python objects (e.g., `Submission`, `Comment`, `Redditor`). This component abstracts away the complexities of JSON parsing and provides a consistent object-oriented view of Reddit data.", + "referenced_source_code": [ + { + "qualified_name": "praw.reddit.Reddit:_prepare_objector", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 0, + "reference_end_line": 0 + } + ] + }, + { + "name": "Resource Accessors", + "description": "Provides a set of high-level, Pythonic methods for interacting with specific Reddit resources and performing common operations (e.g., fetching submissions, comments, or user profiles; performing GET/POST/PUT/DELETE requests). It also includes functionality for resolving Reddit URLs and generating lists of resources.", + "referenced_source_code": [ + { + "qualified_name": "praw.reddit.Reddit:delete", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 0, + "reference_end_line": 0 + }, + { + "qualified_name": "praw.reddit.Reddit:get", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 0, + "reference_end_line": 0 + }, + { + "qualified_name": "praw.reddit.Reddit:patch", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 0, + "reference_end_line": 0 + }, + { + "qualified_name": "praw.reddit.Reddit:post", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 0, + "reference_end_line": 0 + }, + { + "qualified_name": "praw.reddit.Reddit:put", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 0, + "reference_end_line": 0 + }, + { + "qualified_name": "praw.reddit.Reddit:username_available", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 0, + "reference_end_line": 0 + }, + { + "qualified_name": "praw.reddit.Reddit:comment", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 0, + "reference_end_line": 0 + }, + { + "qualified_name": "praw.reddit.Reddit:submission", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 0, + "reference_end_line": 0 + }, + { + "qualified_name": "praw.reddit.Reddit:info", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 0, + "reference_end_line": 0 + }, + { + "qualified_name": "praw.reddit.Reddit:generator", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 0, + "reference_end_line": 0 + }, + { + "qualified_name": "praw.reddit.Reddit:_resolve_share_url", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 0, + "reference_end_line": 0 + } + ] + }, + { + "name": "Rate Limiting Handler", + "description": "Monitors and enforces Reddit API rate limits. It pauses requests when necessary to prevent exceeding the allowed request frequency, ensuring compliance with API terms and preventing service interruptions.", + "referenced_source_code": [ + { + "qualified_name": "praw.reddit.Reddit:_handle_rate_limit", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 0, + "reference_end_line": 0 + } + ] + } + ], + "components_relations": [ + { + "relation": "initializes and manages", + "src_name": "Reddit API Client", + "dst_name": "Authentication Manager" + }, + { + "relation": "initializes and manages", + "src_name": "Reddit API Client", + "dst_name": "HTTP Request Dispatcher" + }, + { + "relation": "initializes and manages", + "src_name": "Reddit API Client", + "dst_name": "Response Object Mapper" + }, + { + "relation": "initializes and manages", + "src_name": "Reddit API Client", + "dst_name": "Rate Limiting Handler" + }, + { + "relation": "exposes", + "src_name": "Reddit API Client", + "dst_name": "Resource Accessors" + }, + { + "relation": "delegates API calls to", + "src_name": "Resource Accessors", + "dst_name": "HTTP Request Dispatcher" + }, + { + "relation": "consults", + "src_name": "HTTP Request Dispatcher", + "dst_name": "Rate Limiting Handler" + }, + { + "relation": "utilizes", + "src_name": "HTTP Request Dispatcher", + "dst_name": "Authentication Manager" + }, + { + "relation": "passes raw responses to", + "src_name": "HTTP Request Dispatcher", + "dst_name": "Response Object Mapper" + }, + { + "relation": "transforms responses and returns to", + "src_name": "Response Object Mapper", + "dst_name": "Resource Accessors" + }, + { + "relation": "configures", + "src_name": "Authentication Manager", + "dst_name": "HTTP Request Dispatcher" + } + ] +} diff --git a/.codeboarding/Reddit_Client.rst b/.codeboarding/Reddit_Client.rst new file mode 100644 index 000000000..2bffa1895 --- /dev/null +++ b/.codeboarding/Reddit_Client.rst @@ -0,0 +1,106 @@ +Reddit Client +============= + +.. mermaid:: + + graph LR + Reddit_API_Client["Reddit API Client"] + Authentication_Manager["Authentication Manager"] + HTTP_Request_Dispatcher["HTTP Request Dispatcher"] + Response_Object_Mapper["Response Object Mapper"] + Resource_Accessors["Resource Accessors"] + Rate_Limiting_Handler["Rate Limiting Handler"] + Reddit_API_Client -- "initializes and manages" --> Authentication_Manager + Reddit_API_Client -- "initializes and manages" --> HTTP_Request_Dispatcher + Reddit_API_Client -- "initializes and manages" --> Response_Object_Mapper + Reddit_API_Client -- "initializes and manages" --> Rate_Limiting_Handler + Reddit_API_Client -- "exposes" --> Resource_Accessors + Resource_Accessors -- "delegates API calls to" --> HTTP_Request_Dispatcher + HTTP_Request_Dispatcher -- "consults" --> Rate_Limiting_Handler + HTTP_Request_Dispatcher -- "utilizes" --> Authentication_Manager + HTTP_Request_Dispatcher -- "passes raw responses to" --> Response_Object_Mapper + Response_Object_Mapper -- "transforms responses and returns to" --> Resource_Accessors + Authentication_Manager -- "configures" --> HTTP_Request_Dispatcher + +| |codeboarding-badge| |demo-badge| |contact-badge| + +.. |codeboarding-badge| image:: https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square + :target: https://github.com/CodeBoarding/CodeBoarding +.. |demo-badge| image:: https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square + :target: https://www.codeboarding.org/demo +.. |contact-badge| image:: https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square + :target: mailto:contact@codeboarding.org + +Details +------- + +The PRAW library's core architecture is centered around the `Reddit API Client`, which serves as the primary interface and orchestrator. This client initializes and manages key components such as the `Authentication Manager`, `HTTP Request Dispatcher`, `Response Object Mapper`, and `Rate Limiting Handler`. User interactions primarily occur through `Resource Accessors`, which expose Pythonic methods for Reddit resources. These accessors delegate API requests to the `HTTP Request Dispatcher`, which handles the actual communication with the Reddit API, incorporating authentication via the `Authentication Manager` and adhering to rate limits managed by the `Rate Limiting Handler`. Raw API responses are then processed by the `Response Object Mapper`, transforming them into structured Python objects before being returned to the `Resource Accessors` for application logic. This design ensures a clear separation of concerns, from API interaction to data transformation and resource management. + +Reddit API Client +^^^^^^^^^^^^^^^^^ + +The primary entry point and orchestrator for the entire PRAW library. It initializes and manages the lifecycle of other core components, providing a unified, high-level interface for accessing various Reddit resources. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit:57-901 `_ + +Authentication Manager +^^^^^^^^^^^^^^^^^^^^^^ + +Handles the setup and management of authentication with the Reddit API, supporting different OAuth flows and credential management. It configures the underlying HTTP client for authenticated requests. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit:_prepare_prawcore `_ +* `praw.reddit.Reddit:_prepare_untrusted_prawcore `_ +* `praw.reddit.Reddit:_prepare_trusted_prawcore `_ +* `praw.reddit.Reddit:_prepare_common_authorizer `_ + +HTTP Request Dispatcher +^^^^^^^^^^^^^^^^^^^^^^^ + +Manages the end-to-end process of sending API requests. This includes preparing the request, dispatching it to the Reddit API, and handling the raw HTTP response. It integrates with the Rate Limiting Handler and may manage asynchronous operations. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit:_objectify_request `_ +* `praw.reddit.Reddit:request `_ +* `praw.reddit.Reddit:_check_for_async `_ + +Response Object Mapper +^^^^^^^^^^^^^^^^^^^^^^ + +Transforms raw JSON responses received from the Reddit API into structured and usable Python objects (e.g., `Submission`, `Comment`, `Redditor`). This component abstracts away the complexities of JSON parsing and provides a consistent object-oriented view of Reddit data. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit:_prepare_objector `_ + +Resource Accessors +^^^^^^^^^^^^^^^^^^ + +Provides a set of high-level, Pythonic methods for interacting with specific Reddit resources and performing common operations (e.g., fetching submissions, comments, or user profiles; performing GET/POST/PUT/DELETE requests). It also includes functionality for resolving Reddit URLs and generating lists of resources. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit:delete `_ +* `praw.reddit.Reddit:get `_ +* `praw.reddit.Reddit:patch `_ +* `praw.reddit.Reddit:post `_ +* `praw.reddit.Reddit:put `_ +* `praw.reddit.Reddit:username_available `_ +* `praw.reddit.Reddit:comment `_ +* `praw.reddit.Reddit:submission `_ +* `praw.reddit.Reddit:info `_ +* `praw.reddit.Reddit:generator `_ +* `praw.reddit.Reddit:_resolve_share_url `_ + +Rate Limiting Handler +^^^^^^^^^^^^^^^^^^^^^ + +Monitors and enforces Reddit API rate limits. It pauses requests when necessary to prevent exceeding the allowed request frequency, ensuring compliance with API terms and preventing service interruptions. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit:_handle_rate_limit `_ diff --git a/.codeboarding/Reddit_Data_Models.json b/.codeboarding/Reddit_Data_Models.json new file mode 100644 index 000000000..4d7f139b8 --- /dev/null +++ b/.codeboarding/Reddit_Data_Models.json @@ -0,0 +1,113 @@ +{ + "description": "The `Reddit Data Models` subsystem, rooted in `praw.models.reddit`, provides a structured, Pythonic interface to various Reddit entities, abstracting the underlying API interactions. It aligns with the project's goal of offering a clean API Wrapper/Client Library by defining distinct objects for different Reddit resources.", + "components": [ + { + "name": "praw.models.reddit.subreddit", + "description": "Manages subreddit properties, moderation, content submission, flair, styles, and user relationships. It serves as a central hub for all subreddit-specific operations.", + "referenced_source_code": [ + { + "qualified_name": "praw.models.reddit.subreddit", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/subreddit.py", + "reference_start_line": 1, + "reference_end_line": 1 + } + ] + }, + { + "name": "praw.models.reddit.submission", + "description": "Manages post details, flair, moderation, and comment retrieval. It encapsulates all functionalities related to a single Reddit post.", + "referenced_source_code": [ + { + "qualified_name": "praw.models.reddit.submission", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/submission.py", + "reference_start_line": 1, + "reference_end_line": 1 + } + ] + }, + { + "name": "praw.models.reddit.comment", + "description": "Handles comment moderation and navigation to its parent or submission. It provides an interface for interacting with individual comments.", + "referenced_source_code": [ + { + "qualified_name": "praw.models.reddit.comment", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/comment.py", + "reference_start_line": 1, + "reference_end_line": 1 + } + ] + }, + { + "name": "praw.models.reddit.redditor", + "description": "Manages user streams and friendship status. It provides an interface for interacting with Reddit user profiles.", + "referenced_source_code": [ + { + "qualified_name": "praw.models.reddit.redditor", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/redditor.py", + "reference_start_line": 1, + "reference_end_line": 1 + } + ] + }, + { + "name": "praw.models.reddit.modmail", + "description": "Parses and manages modmail conversations, providing functionality for interacting with Reddit's internal moderation messaging system.", + "referenced_source_code": [ + { + "qualified_name": "praw.models.reddit.modmail", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/modmail.py", + "reference_start_line": 1, + "reference_end_line": 1 + } + ] + }, + { + "name": "praw.models.reddit.live", + "description": "Manages Live Threads, handling invites, updates, and contributions for real-time event streams.", + "referenced_source_code": [ + { + "qualified_name": "praw.models.reddit.live", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/live.py", + "reference_start_line": 1, + "reference_end_line": 1 + } + ] + }, + { + "name": "praw.models.reddit.widgets", + "description": "Provides an interface for interacting with subreddit widgets, including moderation and creation of different widget types.", + "referenced_source_code": [ + { + "qualified_name": "praw.models.reddit.widgets", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/widgets.py", + "reference_start_line": 1, + "reference_end_line": 1 + } + ] + }, + { + "name": "praw.models.reddit.collections", + "description": "Manages post collections within a subreddit, providing an interface for creating, modifying, and retrieving curated groups of posts.", + "referenced_source_code": [ + { + "qualified_name": "praw.models.reddit.collections", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/collections.py", + "reference_start_line": 1, + "reference_end_line": 1 + } + ] + } + ], + "components_relations": [ + { + "relation": "retrieves associated", + "src_name": "praw.models.reddit.submission", + "dst_name": "praw.models.reddit.comment" + }, + { + "relation": "accesses the parent", + "src_name": "praw.models.reddit.comment", + "dst_name": "praw.models.reddit.submission" + } + ] +} diff --git a/.codeboarding/Reddit_Data_Models.rst b/.codeboarding/Reddit_Data_Models.rst new file mode 100644 index 000000000..d51b2750b --- /dev/null +++ b/.codeboarding/Reddit_Data_Models.rst @@ -0,0 +1,102 @@ +Reddit Data Models +================== + +.. mermaid:: + + graph LR + praw_models_reddit_subreddit["praw.models.reddit.subreddit"] + praw_models_reddit_submission["praw.models.reddit.submission"] + praw_models_reddit_comment["praw.models.reddit.comment"] + praw_models_reddit_redditor["praw.models.reddit.redditor"] + praw_models_reddit_modmail["praw.models.reddit.modmail"] + praw_models_reddit_live["praw.models.reddit.live"] + praw_models_reddit_widgets["praw.models.reddit.widgets"] + praw_models_reddit_collections["praw.models.reddit.collections"] + praw_models_reddit_submission -- "retrieves associated" --> praw_models_reddit_comment + praw_models_reddit_comment -- "accesses the parent" --> praw_models_reddit_submission + +| |codeboarding-badge| |demo-badge| |contact-badge| + +.. |codeboarding-badge| image:: https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square + :target: https://github.com/CodeBoarding/CodeBoarding +.. |demo-badge| image:: https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square + :target: https://www.codeboarding.org/demo +.. |contact-badge| image:: https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square + :target: mailto:contact@codeboarding.org + +Details +------- + +The `Reddit Data Models` subsystem, rooted in `praw.models.reddit`, provides a structured, Pythonic interface to various Reddit entities, abstracting the underlying API interactions. It aligns with the project's goal of offering a clean API Wrapper/Client Library by defining distinct objects for different Reddit resources. + +praw.models.reddit.subreddit +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Manages subreddit properties, moderation, content submission, flair, styles, and user relationships. It serves as a central hub for all subreddit-specific operations. + +**Related Classes/Methods**: + +* `praw.models.reddit.subreddit `_ + +praw.models.reddit.submission +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Manages post details, flair, moderation, and comment retrieval. It encapsulates all functionalities related to a single Reddit post. + +**Related Classes/Methods**: + +* `praw.models.reddit.submission `_ + +praw.models.reddit.comment +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Handles comment moderation and navigation to its parent or submission. It provides an interface for interacting with individual comments. + +**Related Classes/Methods**: + +* `praw.models.reddit.comment `_ + +praw.models.reddit.redditor +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Manages user streams and friendship status. It provides an interface for interacting with Reddit user profiles. + +**Related Classes/Methods**: + +* `praw.models.reddit.redditor `_ + +praw.models.reddit.modmail +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Parses and manages modmail conversations, providing functionality for interacting with Reddit's internal moderation messaging system. + +**Related Classes/Methods**: + +* `praw.models.reddit.modmail `_ + +praw.models.reddit.live +^^^^^^^^^^^^^^^^^^^^^^^ + +Manages Live Threads, handling invites, updates, and contributions for real-time event streams. + +**Related Classes/Methods**: + +* `praw.models.reddit.live `_ + +praw.models.reddit.widgets +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Provides an interface for interacting with subreddit widgets, including moderation and creation of different widget types. + +**Related Classes/Methods**: + +* `praw.models.reddit.widgets `_ + +praw.models.reddit.collections +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Manages post collections within a subreddit, providing an interface for creating, modifying, and retrieving curated groups of posts. + +**Related Classes/Methods**: + +* `praw.models.reddit.collections `_ diff --git a/.codeboarding/analysis.json b/.codeboarding/analysis.json new file mode 100644 index 000000000..f66b30b57 --- /dev/null +++ b/.codeboarding/analysis.json @@ -0,0 +1,265 @@ +{ + "description": "The PRAW library's architecture is centered around the Reddit Client, which acts as the primary orchestrator for all interactions with the Reddit API. This client relies on the Configuration Manager to load and manage its operational settings, ensuring proper initialization. For actual network communication and secure authentication, the Reddit Client delegates to the Low-Level API Connector (an external dependency, `prawcore`), which handles the intricacies of HTTP requests and OAuth2. Upon receiving raw JSON responses from the API via the Low-Level API Connector, the Reddit Client forwards this data to the Object Transformer. The Object Transformer is responsible for converting these raw responses into structured Python objects, which are instances of the Reddit Data Models (e.g., `Subreddit`, `Submission`). These data models represent the various entities within Reddit and can, in turn, initiate further requests through the Reddit Client to fetch related data. Complementing this core interaction, the Listing & Streaming component provides efficient mechanisms for iterating over collections of Reddit items, including real-time data streams, by fetching data through the Reddit Client and generating instances of the Reddit Data Models for consumption. This design ensures a clear separation of concerns, with the Reddit Client managing the overall flow, specialized components handling data transformation and retrieval, and a robust set of data models representing the API's entities.", + "components": [ + { + "name": "Reddit Client", + "description": "The primary interface for interacting with the Reddit API, managing authentication and request dispatch.", + "referenced_source_code": [ + { + "qualified_name": "praw/reddit.py", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 1, + "reference_end_line": 1 + } + ], + "assigned_files": [ + "praw/reddit.py" + ], + "can_expand": true + }, + { + "name": "Configuration Manager", + "description": "Manages loading and accessing PRAW's configuration settings.", + "referenced_source_code": [ + { + "qualified_name": "praw/config.py", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/config.py", + "reference_start_line": 1, + "reference_end_line": 1 + } + ], + "assigned_files": [ + "praw/config.py" + ], + "can_expand": true + }, + { + "name": "Low-Level API Connector", + "description": "An external dependency responsible for actual HTTP communication and OAuth2 authentication with the Reddit API.", + "referenced_source_code": [ + { + "qualified_name": "prawcore", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 527, + "reference_end_line": 546 + } + ], + "assigned_files": [], + "can_expand": true + }, + { + "name": "Object Transformer", + "description": "Converts raw JSON data from the Reddit API into structured PRAW Python objects.", + "referenced_source_code": [ + { + "qualified_name": "praw/objector.py", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py", + "reference_start_line": 1, + "reference_end_line": 1 + } + ], + "assigned_files": [ + "praw/objector.py" + ], + "can_expand": true + }, + { + "name": "Reddit Data Models", + "description": "A collection of classes representing various Reddit entities (e.g., `Subreddit`, `Submission`, `Comment`).", + "referenced_source_code": [ + { + "qualified_name": "praw.models.reddit", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit", + "reference_start_line": 1, + "reference_end_line": 1 + } + ], + "assigned_files": [ + "praw/models/__init__.py", + "praw/models/mod_note.py", + "praw/models/base.py", + "praw/models/util.py", + "praw/models/front.py", + "praw/models/preferences.py", + "praw/models/redditors.py", + "praw/models/mod_action.py", + "praw/models/user.py", + "praw/models/comment_forest.py", + "praw/models/mod_notes.py", + "praw/models/trophy.py", + "praw/models/helpers.py", + "praw/models/inbox.py", + "praw/models/subreddits.py", + "praw/models/stylesheet.py", + "praw/models/auth.py", + "praw/models/reddit/__init__.py", + "praw/models/reddit/submission.py", + "praw/models/reddit/widgets.py", + "praw/models/reddit/base.py", + "praw/models/reddit/subreddit.py", + "praw/models/reddit/removal_reasons.py", + "praw/models/reddit/draft.py", + "praw/models/reddit/user_subreddit.py", + "praw/models/reddit/rules.py", + "praw/models/reddit/poll.py", + "praw/models/reddit/redditor.py", + "praw/models/reddit/modmail.py", + "praw/models/reddit/comment.py", + "praw/models/reddit/collections.py", + "praw/models/reddit/emoji.py", + "praw/models/reddit/more.py", + "praw/models/reddit/multi.py", + "praw/models/reddit/live.py", + "praw/models/reddit/message.py", + "praw/models/reddit/inline_media.py", + "praw/models/reddit/wikipage.py", + "praw/models/reddit/mixins/__init__.py", + "praw/models/reddit/mixins/inboxtoggleable.py", + "praw/models/reddit/mixins/inboxable.py", + "praw/models/reddit/mixins/savable.py", + "praw/models/reddit/mixins/reportable.py", + "praw/models/reddit/mixins/fullname.py", + "praw/models/reddit/mixins/messageable.py", + "praw/models/reddit/mixins/modnote.py", + "praw/models/reddit/mixins/replyable.py", + "praw/models/reddit/mixins/editable.py", + "praw/models/reddit/mixins/votable.py" + ], + "can_expand": true + }, + { + "name": "Listing & Streaming", + "description": "Provides mechanisms for efficiently retrieving and iterating over collections of Reddit items, including real-time data streams.", + "referenced_source_code": [ + { + "qualified_name": "praw.models.listing", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing", + "reference_start_line": 1, + "reference_end_line": 1 + } + ], + "assigned_files": [ + "praw/models/list/moderated.py", + "praw/models/list/__init__.py", + "praw/models/list/base.py", + "praw/models/list/draft.py", + "praw/models/list/redditor.py", + "praw/models/list/trophy.py", + "praw/models/listing/__init__.py", + "praw/models/listing/domain.py", + "praw/models/listing/listing.py", + "praw/models/listing/generator.py", + "praw/models/listing/mixins/__init__.py", + "praw/models/listing/mixins/submission.py", + "praw/models/listing/mixins/base.py", + "praw/models/listing/mixins/subreddit.py", + "praw/models/listing/mixins/redditor.py", + "praw/models/listing/mixins/rising.py" + ], + "can_expand": true + }, + { + "name": "Unclassified", + "description": "Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies)", + "referenced_source_code": [], + "assigned_files": [ + "pre_push.py", + "tools/__init__.py", + "tools/set_version.py", + "tools/set_active_docs.py", + "tools/static_word_checks.py", + "tools/bump_version.py", + "tools/check_documentation.py", + "tools/extract_log_entry.py", + "docs/conf.py", + "docs/examples/obtain_refresh_token.py", + "docs/examples/lmgtfy_bot.py", + "praw/__init__.py", + "praw/const.py", + "praw/endpoints.py", + "praw/exceptions.py", + "praw/util/__init__.py", + "praw/util/cache.py", + "praw/util/snake.py" + ], + "can_expand": false + }, + { + "name": "Unclassified", + "description": "Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies)", + "referenced_source_code": [], + "assigned_files": [], + "can_expand": false + }, + { + "name": "Unclassified", + "description": "Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies)", + "referenced_source_code": [], + "assigned_files": [], + "can_expand": false + }, + { + "name": "Unclassified", + "description": "Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies)", + "referenced_source_code": [], + "assigned_files": [], + "can_expand": false + }, + { + "name": "Unclassified", + "description": "Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies)", + "referenced_source_code": [], + "assigned_files": [], + "can_expand": false + }, + { + "name": "Unclassified", + "description": "Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies)", + "referenced_source_code": [], + "assigned_files": [], + "can_expand": false + } + ], + "components_relations": [ + { + "relation": "loads settings from", + "src_name": "Reddit Client", + "dst_name": "Configuration Manager" + }, + { + "relation": "delegates requests to", + "src_name": "Reddit Client", + "dst_name": "Low-Level API Connector" + }, + { + "relation": "returns raw response to", + "src_name": "Low-Level API Connector", + "dst_name": "Reddit Client" + }, + { + "relation": "sends raw data to", + "src_name": "Reddit Client", + "dst_name": "Object Transformer" + }, + { + "relation": "instantiates", + "src_name": "Object Transformer", + "dst_name": "Reddit Data Models" + }, + { + "relation": "initiates requests via", + "src_name": "Reddit Data Models", + "dst_name": "Reddit Client" + }, + { + "relation": "fetches data via", + "src_name": "Listing & Streaming", + "dst_name": "Reddit Client" + }, + { + "relation": "generates", + "src_name": "Listing & Streaming", + "dst_name": "Reddit Data Models" + } + ] +} diff --git a/.codeboarding/codeboarding_version.json b/.codeboarding/codeboarding_version.json new file mode 100644 index 000000000..e7e6c2fab --- /dev/null +++ b/.codeboarding/codeboarding_version.json @@ -0,0 +1,4 @@ +{ + "commit_hash": "38807c47c93eb29b7c540e44196a7adf38433464", + "code_boarding_version": "0.2.0" +} diff --git a/.codeboarding/overview.rst b/.codeboarding/overview.rst new file mode 100644 index 000000000..791a708b0 --- /dev/null +++ b/.codeboarding/overview.rst @@ -0,0 +1,154 @@ +Overview +======== + +.. mermaid:: + + graph LR + Reddit_Client["Reddit Client"] + Configuration_Manager["Configuration Manager"] + Low_Level_API_Connector["Low-Level API Connector"] + Object_Transformer["Object Transformer"] + Reddit_Data_Models["Reddit Data Models"] + Listing_Streaming["Listing & Streaming"] + Unclassified["Unclassified"] + Unclassified["Unclassified"] + Unclassified["Unclassified"] + Unclassified["Unclassified"] + Unclassified["Unclassified"] + Unclassified["Unclassified"] + Reddit_Client -- "loads settings from" --> Configuration_Manager + Reddit_Client -- "delegates requests to" --> Low_Level_API_Connector + Low_Level_API_Connector -- "returns raw response to" --> Reddit_Client + Reddit_Client -- "sends raw data to" --> Object_Transformer + Object_Transformer -- "instantiates" --> Reddit_Data_Models + Reddit_Data_Models -- "initiates requests via" --> Reddit_Client + Listing_Streaming -- "fetches data via" --> Reddit_Client + Listing_Streaming -- "generates" --> Reddit_Data_Models + click Reddit_Client href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Reddit_Client.html" "Details" + click Configuration_Manager href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Configuration_Manager.html" "Details" + click Low_Level_API_Connector href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Low_Level_API_Connector.html" "Details" + click Object_Transformer href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Object_Transformer.html" "Details" + click Reddit_Data_Models href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Reddit_Data_Models.html" "Details" + click Listing_Streaming href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Listing_Streaming.html" "Details" + +| |codeboarding-badge| |demo-badge| |contact-badge| + +.. |codeboarding-badge| image:: https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square + :target: https://github.com/CodeBoarding/CodeBoarding +.. |demo-badge| image:: https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square + :target: https://www.codeboarding.org/demo +.. |contact-badge| image:: https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square + :target: mailto:contact@codeboarding.org + +Details +------- + +The PRAW library's architecture is centered around the Reddit Client, which acts as the primary orchestrator for all interactions with the Reddit API. This client relies on the Configuration Manager to load and manage its operational settings, ensuring proper initialization. For actual network communication and secure authentication, the Reddit Client delegates to the Low-Level API Connector (an external dependency, `prawcore`), which handles the intricacies of HTTP requests and OAuth2. Upon receiving raw JSON responses from the API via the Low-Level API Connector, the Reddit Client forwards this data to the Object Transformer. The Object Transformer is responsible for converting these raw responses into structured Python objects, which are instances of the Reddit Data Models (e.g., `Subreddit`, `Submission`). These data models represent the various entities within Reddit and can, in turn, initiate further requests through the Reddit Client to fetch related data. Complementing this core interaction, the Listing & Streaming component provides efficient mechanisms for iterating over collections of Reddit items, including real-time data streams, by fetching data through the Reddit Client and generating instances of the Reddit Data Models for consumption. This design ensures a clear separation of concerns, with the Reddit Client managing the overall flow, specialized components handling data transformation and retrieval, and a robust set of data models representing the API's entities. + +Reddit Client +^^^^^^^^^^^^^ + +:ref:`Expand ` + +The primary interface for interacting with the Reddit API, managing authentication and request dispatch. + +**Related Classes/Methods**: + +* `praw/reddit.py `_ + +Configuration Manager +^^^^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +Manages loading and accessing PRAW's configuration settings. + +**Related Classes/Methods**: + +* `praw/config.py `_ + +Low-Level API Connector +^^^^^^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +An external dependency responsible for actual HTTP communication and OAuth2 authentication with the Reddit API. + +**Related Classes/Methods**: + +* `prawcore:527-546 `_ + +Object Transformer +^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +Converts raw JSON data from the Reddit API into structured PRAW Python objects. + +**Related Classes/Methods**: + +* `praw/objector.py `_ + +Reddit Data Models +^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +A collection of classes representing various Reddit entities (e.g., `Subreddit`, `Submission`, `Comment`). + +**Related Classes/Methods**: + +* `praw.models.reddit `_ + +Listing & Streaming +^^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +Provides mechanisms for efficiently retrieving and iterating over collections of Reddit items, including real-time data streams. + +**Related Classes/Methods**: + +* `praw.models.listing `_ + +Unclassified +^^^^^^^^^^^^ + +Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies) + +**Related Classes/Methods**: *None* + +Unclassified +^^^^^^^^^^^^ + +Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies) + +**Related Classes/Methods**: *None* + +Unclassified +^^^^^^^^^^^^ + +Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies) + +**Related Classes/Methods**: *None* + +Unclassified +^^^^^^^^^^^^ + +Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies) + +**Related Classes/Methods**: *None* + +Unclassified +^^^^^^^^^^^^ + +Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies) + +**Related Classes/Methods**: *None* + +Unclassified +^^^^^^^^^^^^ + +Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies) + +**Related Classes/Methods**: *None* diff --git a/.github/workflows/docs_codeboarding.yml b/.github/workflows/docs_codeboarding.yml new file mode 100644 index 000000000..04f1a9d05 --- /dev/null +++ b/.github/workflows/docs_codeboarding.yml @@ -0,0 +1,150 @@ +name: CodeBoarding Documentation update workflow + +on: + schedule: + - cron: '0 20 * * 0' # Every Sunday at 8:00 PM UTC + workflow_dispatch: + inputs: + repository_url: + description: 'Repository URL to analyze' + required: false + default: 'https://github.com/praw-dev/praw' + type: string + source_branch: + description: 'Source branch to analyze' + required: false + default: 'main' + type: string + target_branch: + description: 'Target branch for documentation' + required: false + default: 'main' + type: string + output_directory: + description: 'Output directory for documentation files' + required: false + default: '.codeboarding' + type: string + output_format: + description: 'Output format for documentation' + required: false + default: '.rst' + type: choice + options: + - '.rst' + - '.md' + - '.mdx' + push: + branches: + - master + - main + +jobs: + update-docs: + runs-on: ubuntu-latest + timeout-minutes: 45 + permissions: + contents: write + pull-requests: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + token: ${{ secrets.GITHUB_TOKEN }} + fetch-depth: 0 # Required to access branch history + + # Determine branches based on context + - name: Set branch variables + id: set-branches + run: | + if [ "${{ github.event.inputs.source_branch }}" != "" ] && [ "${{ github.event.inputs.target_branch }}" != "" ]; then + echo "source_branch=${{ github.event.inputs.source_branch }}" >> $GITHUB_OUTPUT + echo "target_branch=${{ github.event.inputs.target_branch }}" >> $GITHUB_OUTPUT + echo "repository_url=${{ github.event.inputs.repository_url || format('https://github.com/{0}', github.repository) }}" >> $GITHUB_OUTPUT + else + echo "source_branch=main" >> $GITHUB_OUTPUT + echo "target_branch=main" >> $GITHUB_OUTPUT + echo "repository_url=https://github.com/${{ github.repository }}" >> $GITHUB_OUTPUT + fi + + - name: Fetch CodeBoarding Documentation + timeout-minutes: 30 + id: codeboarding + uses: CodeBoarding/CodeBoarding-GHAction@0.1.2 + with: + repository_url: ${{ steps.set-branches.outputs.repository_url }} + source_branch: ${{ steps.set-branches.outputs.source_branch }} + target_branch: ${{ steps.set-branches.outputs.target_branch }} + output_directory: ${{ github.event.inputs.output_directory || '.codeboarding' }} + output_format: ${{ github.event.inputs.output_format || '.rst' }} + + - name: Display Action Results + run: | + echo "Documentation files created: ${{ steps.codeboarding.outputs.markdown_files_created }}" + echo "JSON files created: ${{ steps.codeboarding.outputs.json_files_created }}" + echo "Documentation directory: ${{ steps.codeboarding.outputs.output_directory }}" + echo "JSON directory: ${{ steps.codeboarding.outputs.json_directory }}" + echo "Has changes: ${{ steps.codeboarding.outputs.has_changes }}" + + # Move .rst files from .codeboarding/ to docs/architecture_overview/ folder + - name: Move .rst files to architecture overview + run: | + # Create docs/architecture_overview directory if it doesn't exist + mkdir -p docs/architecture_overview + + # Check if .codeboarding/ exists and contains .rst files + if [ -d ".codeboarding" ] && [ -n "$(find .codeboarding -name '*.rst' -type f)" ]; then + echo "Moving .rst files from .codeboarding/ to docs/architecture_overview/" + + # Copy .rst files to docs/architecture_overview folder + cp .codeboarding/*.rst docs/architecture_overview/ 2>/dev/null || echo "No .rst files found to copy" + + # Also copy any subdirectories with .rst files + find .codeboarding -type d -exec sh -c ' + for dir do + if [ -n "$(find "$dir" -maxdepth 1 -name "*.rst" -type f)" ]; then + echo "Copying .rst files from $dir" + cp "$dir"/*.rst docs/architecture_overview/ 2>/dev/null || echo "No .rst files found in $dir" + fi + done + ' sh {} + + + echo ".rst files moved to architecture overview successfully" + else + echo "No .codeboarding/ directory or .rst files found" + fi + + # Check if we have any changes to commit + - name: Check for changes + id: git-changes + run: | + if [ -n "$(git status --porcelain)" ]; then + echo "has_git_changes=true" >> $GITHUB_OUTPUT + else + echo "has_git_changes=false" >> $GITHUB_OUTPUT + fi + + - name: Commit and push changes + if: steps.git-changes.outputs.has_git_changes == 'true' && steps.codeboarding.outputs.has_changes == 'true' + run: | + git config --local user.email "action@github.com" + git config --local user.name "GitHub Action" + git add . + git commit -m "docs: update codeboarding documentation + + ## 📚 Documentation Update + This commit contains updated documentation files fetched from the CodeBoarding service. + + ### 📊 Summary + - Documentation files created/updated: ${{ steps.codeboarding.outputs.markdown_files_created }} + - JSON files created/updated: ${{ steps.codeboarding.outputs.json_files_created }} + - Documentation directory: ${{ steps.codeboarding.outputs.output_directory }}/ + - JSON directory: ${{ steps.codeboarding.outputs.json_directory }}/ + - Output format: ${{ github.event.inputs.output_format || '.rst' }} + - Repository analyzed: ${{ steps.set-branches.outputs.repository_url }} + - Source branch: ${{ steps.set-branches.outputs.source_branch }} + - Target branch: ${{ steps.set-branches.outputs.target_branch }} + + 🤖 This commit was automatically generated by the CodeBoarding documentation update workflow." + git push \ No newline at end of file diff --git a/docs/architecture_overview/Configuration_Manager.rst b/docs/architecture_overview/Configuration_Manager.rst new file mode 100644 index 000000000..edd120c59 --- /dev/null +++ b/docs/architecture_overview/Configuration_Manager.rst @@ -0,0 +1,52 @@ +Configuration Manager +===================== + +.. mermaid:: + + graph LR + Configuration_Manager["Configuration Manager"] + Reddit_API_Client["Reddit API Client"] + Unclassified["Unclassified"] + Configuration_Manager -- "provides configuration to" --> Reddit_API_Client + click Configuration_Manager href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Configuration_Manager.html" "Details" + +| |codeboarding-badge| |demo-badge| |contact-badge| + +.. |codeboarding-badge| image:: https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square + :target: https://github.com/CodeBoarding/CodeBoarding +.. |demo-badge| image:: https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square + :target: https://www.codeboarding.org/demo +.. |contact-badge| image:: https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square + :target: mailto:contact@codeboarding.org + +Details +------- + +The PRAW library's core architecture is centered around two main components: the Configuration Manager and the Reddit API Client. The Configuration Manager, implemented by the praw.config.Config class, is responsible for abstracting and providing all necessary configuration settings, such as API credentials and user agent information, which can be sourced from praw.ini files or environment variables. This ensures a flexible and centralized approach to managing application settings. The Reddit API Client, represented by the praw.Reddit.Reddit class, serves as the primary interface for interacting with the Reddit API. It critically depends on the Configuration Manager to obtain its initialization parameters, enabling it to establish authenticated sessions and facilitate all subsequent API requests. This clear separation of concerns allows for robust configuration handling and a streamlined API interaction experience. + +Configuration Manager +^^^^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +This component is responsible for centralizing the loading, parsing, and provision of PRAW's configuration settings. It abstracts the underlying storage mechanisms (e.g., praw.ini file, environment variables) and offers a unified interface for retrieving critical API access parameters such as client ID, client secret, user agent, and redirect URI. These parameters are fundamental for establishing a connection and authenticating with the Reddit API. + +**Related Classes/Methods**: + +* praw.config.Config + +Reddit API Client +^^^^^^^^^^^^^^^^^ + +As the main API client, this component serves as the primary interface for all interactions with the Reddit API. It requires the configuration parameters managed by the Configuration Manager to initialize itself, authenticate, and make requests. It acts as the entry point for developers to access various Reddit resources and functionalities. + +**Related Classes/Methods**: + +* praw.Reddit.Reddit:57-901 + +Unclassified +^^^^^^^^^^^^ + +Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies) + +**Related Classes/Methods**: *None* diff --git a/docs/architecture_overview/Listing_Streaming.rst b/docs/architecture_overview/Listing_Streaming.rst new file mode 100644 index 000000000..ff41e468c --- /dev/null +++ b/docs/architecture_overview/Listing_Streaming.rst @@ -0,0 +1,108 @@ +Listing Streaming +================= + +.. mermaid:: + + graph LR + ListingGenerator["ListingGenerator"] + BaseListingMixin["BaseListingMixin"] + SubredditListingMixin["SubredditListingMixin"] + RedditorListingMixin["RedditorListingMixin"] + StreamGenerator["StreamGenerator"] + RedditorsStream["RedditorsStream"] + InboxStream["InboxStream"] + SubredditContentStream["SubredditContentStream"] + SubredditListingMixin -- "specializes" --> BaseListingMixin + RedditorListingMixin -- "specializes" --> BaseListingMixin + BaseListingMixin -- "utilizes" --> ListingGenerator + SubredditListingMixin -- "utilizes" --> ListingGenerator + RedditorListingMixin -- "utilizes" --> ListingGenerator + RedditorsStream -- "leverages" --> StreamGenerator + InboxStream -- "leverages" --> StreamGenerator + SubredditContentStream -- "leverages" --> StreamGenerator + +| |codeboarding-badge| |demo-badge| |contact-badge| + +.. |codeboarding-badge| image:: https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square + :target: https://github.com/CodeBoarding/CodeBoarding +.. |demo-badge| image:: https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square + :target: https://www.codeboarding.org/demo +.. |contact-badge| image:: https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square + :target: mailto:contact@codeboarding.org + +Details +------- + +The PRAW library's data retrieval architecture is primarily composed of two distinct but complementary patterns: listing generation and stream generation. The ListingGenerator forms the backbone for paginated data retrieval, efficiently fetching and iterating through large datasets from the Reddit API. This core functionality is extended and specialized by BaseListingMixin, SubredditListingMixin, and RedditorListingMixin, which provide context-specific listing capabilities for general, subreddit, and redditor content, respectively. For real-time data, the StreamGenerator (implemented as stream_generator utility) offers a robust mechanism for continuous data delivery, handling deduplication and rate limiting. This utility is leveraged by higher-level stream methods within Redditors, Inbox, and Subreddits classes, providing user-friendly entry points for accessing live streams of redditors, inbox messages, and subreddit content. This dual approach ensures comprehensive and efficient access to both historical and real-time Reddit data. + +ListingGenerator +^^^^^^^^^^^^^^^^ + +Manages the iteration and pagination of items from Reddit API responses. It handles fetching data in batches, extracting relevant sub-lists, and providing an iterable interface to the user, abstracting away pagination details. This component is crucial for efficiently handling large datasets from the Reddit API. + +**Related Classes/Methods**: + +* `ListingGenerator:17-103 `_ + +BaseListingMixin +^^^^^^^^^^^^^^^^ + +Provides foundational listing methods such as `hot`, `new`, `top`, and `controversial`. It prepares generic API requests and validates time filters applicable across various Reddit resources, serving as a common interface for listing operations. + +**Related Classes/Methods**: + +* `BaseListingMixin:15-149 `_ + +SubredditListingMixin +^^^^^^^^^^^^^^^^^^^^^ + +Specializes listing functionality for subreddit-specific content, including comments and submissions within a subreddit. It determines appropriate API paths for subreddit-related data, extending the base listing capabilities. + +**Related Classes/Methods**: + +* `SubredditListingMixin:49-73 `_ + +RedditorListingMixin +^^^^^^^^^^^^^^^^^^^^ + +Specializes listing functionality for redditor-specific content, such as comments and submissions made by a particular user. It creates sub-listings tailored to user activity, providing a user-centric view of Reddit data. + +**Related Classes/Methods**: + +* `RedditorListingMixin:35-185 `_ + +StreamGenerator +^^^^^^^^^^^^^^^ + +This component, implemented as the `stream_generator` function, provides a generic, low-level mechanism for continuously yielding new items from a source. It manages the stream's state, handles deduplication using a `BoundedSet`, and incorporates exponential backoff for rate limiting, forming the core engine for all streaming operations. This is the fundamental utility for real-time data. + +**Related Classes/Methods**: + +* `stream_generator:36-163 `_ + +RedditorsStream +^^^^^^^^^^^^^^^ + +Represents the `stream` method within the `Redditors` class, acting as an entry point for initiating and managing a continuous stream of new redditors as they are created or become active. It provides a high-level interface for accessing real-time user data by leveraging the `stream_generator` utility. + +**Related Classes/Methods**: + +* `Redditors.stream:93-104 `_ + +InboxStream +^^^^^^^^^^^ + +Represents the `stream` method within the `Inbox` class, acting as an entry point for initiating and managing a continuous stream of unread inbox messages for the authenticated user. This component is vital for real-time notification and interaction features, leveraging the `stream_generator` utility. + +**Related Classes/Methods**: + +* `Inbox.stream:229-247 `_ + +SubredditContentStream +^^^^^^^^^^^^^^^^^^^^^^ + +Represents the `stream` method within the `Subreddits` class, providing access to streams of content related to a specific subreddit, including specialized moderation streams. This allows for real-time monitoring of activity within a subreddit by leveraging the `stream_generator` utility. + +**Related Classes/Methods**: + +* `Subreddits.stream:124-133 `_ diff --git a/docs/architecture_overview/Low_Level_API_Connector.rst b/docs/architecture_overview/Low_Level_API_Connector.rst new file mode 100644 index 000000000..62dcdc029 --- /dev/null +++ b/docs/architecture_overview/Low_Level_API_Connector.rst @@ -0,0 +1,86 @@ +Low Level Api Connector +======================= + +.. mermaid:: + + graph LR + Reddit_Client["Reddit Client"] + Low_Level_API_Connector["Low-Level API Connector"] + Authentication_Module["Authentication Module"] + Data_Models_Objects["Data Models/Objects"] + Configuration_Management["Configuration Management"] + Reddit_Client -- "utilizes" --> Low_Level_API_Connector + Reddit_Client -- "depends on" --> Low_Level_API_Connector + Authentication_Module -- "configures" --> Low_Level_API_Connector + Authentication_Module -- "provides authentication context to" --> Low_Level_API_Connector + Reddit_Client -- "interacts with" --> Authentication_Module + Reddit_Client -- "uses" --> Data_Models_Objects + Reddit_Client -- "loads settings via" --> Configuration_Management + Data_Models_Objects -- "are populated by" --> Low_Level_API_Connector + Authentication_Module -- "reads settings from" --> Configuration_Management + click Reddit_Client href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Reddit_Client.html" "Details" + click Low_Level_API_Connector href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Low_Level_API_Connector.html" "Details" + +| |codeboarding-badge| |demo-badge| |contact-badge| + +.. |codeboarding-badge| image:: https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square + :target: https://github.com/CodeBoarding/CodeBoarding +.. |demo-badge| image:: https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square + :target: https://www.codeboarding.org/demo +.. |contact-badge| image:: https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square + :target: mailto:contact@codeboarding.org + +Details +------- + +The `praw` library provides a high-level, Pythonic interface for interacting with the Reddit API. At its core, the `Reddit Client` acts as the primary orchestrator, managing user requests and coordinating with other internal components. It leverages an `Authentication Module` to handle various OAuth2 flows and token management, ensuring secure access to Reddit resources. `Configuration Management` centralizes the loading and parsing of settings, making the client adaptable to different environments. All interactions with Reddit's data are facilitated through `Data Models/Objects`, which abstract API responses into intuitive Python objects. For the actual network communication and low-level OAuth2 intricacies, `praw` relies on the `Low-Level API Connector` (prawcore), an external dependency that handles the complexities of HTTP requests and responses, thereby decoupling `praw` from the underlying network layer. + +Reddit Client +^^^^^^^^^^^^^ + +:ref:`Expand ` + +The primary entry point for users to interact with the Reddit API. It orchestrates calls to other components to fulfill user requests, providing a high-level, Pythonic interface to Reddit resources. + +**Related Classes/Methods**: + +* `praw.Reddit `_ + +Low-Level API Connector +^^^^^^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +An external dependency, `prawcore`, which is solely responsible for handling the low-level HTTP communication with the Reddit API. It manages the actual network requests, responses, and the intricacies of OAuth2 authentication flows, abstracting these complexities from the higher-level `praw` library. + +**Related Classes/Methods**: + +* `prawcore:527-546 `_ + +Authentication Module +^^^^^^^^^^^^^^^^^^^^^ + +Manages the various OAuth2 authentication flows (e.g., script, installed app, web app) and handles the storage and refreshing of access tokens. + +**Related Classes/Methods**: + +* `praw.auth `_ + +Data Models/Objects +^^^^^^^^^^^^^^^^^^^ + +Represents Reddit API resources (e.g., `Submission`, `Comment`, `Subreddit`, `User`) as Python objects, providing attribute access and methods for interaction. + +**Related Classes/Methods**: + +* `praw.models.submission.Submission `_ +* `praw.models.subreddit.Subreddit `_ + +Configuration Management +^^^^^^^^^^^^^^^^^^^^^^^^ + +Handles the loading, parsing, and management of configuration settings (e.g., client ID, client secret, user agent) from various sources (e.g., `praw.ini`, environment variables). + +**Related Classes/Methods**: + +* `praw.config `_ diff --git a/docs/architecture_overview/Object_Transformer.rst b/docs/architecture_overview/Object_Transformer.rst new file mode 100644 index 000000000..0da8a3e3a --- /dev/null +++ b/docs/architecture_overview/Object_Transformer.rst @@ -0,0 +1,77 @@ +Object Transformer +================== + +.. mermaid:: + + graph LR + Objector_Class["Objector Class"] + Objector_objectify_Method["Objector.objectify Method"] + Objector__objectify_dict_Method["Objector._objectify_dict Method"] + Objector_check_error_Method["Objector.check_error Method"] + Objector_parse_error_Method["Objector.parse_error Method"] + Objector_Class -- "orchestrates" --> Objector_objectify_Method + Objector_Class -- "orchestrates" --> Objector__objectify_dict_Method + Objector_Class -- "orchestrates" --> Objector_check_error_Method + Objector_Class -- "orchestrates" --> Objector_parse_error_Method + Objector_objectify_Method -- "delegates to" --> Objector__objectify_dict_Method + Objector_objectify_Method -- "invokes" --> Objector_check_error_Method + Objector_check_error_Method -- "calls" --> Objector_parse_error_Method + +| |codeboarding-badge| |demo-badge| |contact-badge| + +.. |codeboarding-badge| image:: https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square + :target: https://github.com/CodeBoarding/CodeBoarding +.. |demo-badge| image:: https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square + :target: https://www.codeboarding.org/demo +.. |contact-badge| image:: https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square + :target: mailto:contact@codeboarding.org + +Details +------- + +The `Object Transformer` subsystem is primarily defined by the `praw.objector` module, specifically the `Objector` class and its associated methods. Its core responsibility is to convert raw JSON data received from the Reddit API into structured, type-safe PRAW Python objects, while also handling API-specific error detection and parsing. + +Objector Class +^^^^^^^^^^^^^^ + +Acts as the central facade and orchestrator for the entire objectification process. It manages the conversion of various raw data types (dictionaries, lists, booleans, etc.) into their corresponding PRAW objects and integrates error checking. + +**Related Classes/Methods**: + +* `praw.objector.Objector:17-263 `_ + +Objector.objectify Method +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Serves as the main public entry point for initiating the transformation of raw data. It intelligently handles different input types (e.g., `None`, `list`, `bool`, `dict`) and directs the flow to appropriate internal methods, including an initial check for embedded API errors. + +**Related Classes/Methods**: + +* `praw.objector.Objector:objectify `_ + +Objector._objectify_dict Method +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Specializes in converting dictionary-structured data, which is typical for Reddit API responses, into specific PRAW objects. It contains conditional logic to identify the precise type of Reddit object (e.g., `ModmailConversation`, `Subreddit`, `Redditor`) based on key fields and applies the relevant parsing logic. + +**Related Classes/Methods**: + +* `praw.objector.Objector:_objectify_dict `_ + +Objector.check_error Method +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Examines the raw input data to determine if it represents an API error response. If an error is detected, it triggers the raising of a `RedditAPIException`, ensuring that API-level issues are properly surfaced. + +**Related Classes/Methods**: + +* `praw.objector.Objector:check_error `_ + +Objector.parse_error Method +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Extracts and formats detailed error messages from the raw API response, converting them into a structured `RedditAPIException` instance. This provides clear and actionable error information to the user. + +**Related Classes/Methods**: + +* `praw.objector.Objector:parse_error `_ diff --git a/docs/architecture_overview/Reddit_Client.rst b/docs/architecture_overview/Reddit_Client.rst new file mode 100644 index 000000000..2bffa1895 --- /dev/null +++ b/docs/architecture_overview/Reddit_Client.rst @@ -0,0 +1,106 @@ +Reddit Client +============= + +.. mermaid:: + + graph LR + Reddit_API_Client["Reddit API Client"] + Authentication_Manager["Authentication Manager"] + HTTP_Request_Dispatcher["HTTP Request Dispatcher"] + Response_Object_Mapper["Response Object Mapper"] + Resource_Accessors["Resource Accessors"] + Rate_Limiting_Handler["Rate Limiting Handler"] + Reddit_API_Client -- "initializes and manages" --> Authentication_Manager + Reddit_API_Client -- "initializes and manages" --> HTTP_Request_Dispatcher + Reddit_API_Client -- "initializes and manages" --> Response_Object_Mapper + Reddit_API_Client -- "initializes and manages" --> Rate_Limiting_Handler + Reddit_API_Client -- "exposes" --> Resource_Accessors + Resource_Accessors -- "delegates API calls to" --> HTTP_Request_Dispatcher + HTTP_Request_Dispatcher -- "consults" --> Rate_Limiting_Handler + HTTP_Request_Dispatcher -- "utilizes" --> Authentication_Manager + HTTP_Request_Dispatcher -- "passes raw responses to" --> Response_Object_Mapper + Response_Object_Mapper -- "transforms responses and returns to" --> Resource_Accessors + Authentication_Manager -- "configures" --> HTTP_Request_Dispatcher + +| |codeboarding-badge| |demo-badge| |contact-badge| + +.. |codeboarding-badge| image:: https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square + :target: https://github.com/CodeBoarding/CodeBoarding +.. |demo-badge| image:: https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square + :target: https://www.codeboarding.org/demo +.. |contact-badge| image:: https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square + :target: mailto:contact@codeboarding.org + +Details +------- + +The PRAW library's core architecture is centered around the `Reddit API Client`, which serves as the primary interface and orchestrator. This client initializes and manages key components such as the `Authentication Manager`, `HTTP Request Dispatcher`, `Response Object Mapper`, and `Rate Limiting Handler`. User interactions primarily occur through `Resource Accessors`, which expose Pythonic methods for Reddit resources. These accessors delegate API requests to the `HTTP Request Dispatcher`, which handles the actual communication with the Reddit API, incorporating authentication via the `Authentication Manager` and adhering to rate limits managed by the `Rate Limiting Handler`. Raw API responses are then processed by the `Response Object Mapper`, transforming them into structured Python objects before being returned to the `Resource Accessors` for application logic. This design ensures a clear separation of concerns, from API interaction to data transformation and resource management. + +Reddit API Client +^^^^^^^^^^^^^^^^^ + +The primary entry point and orchestrator for the entire PRAW library. It initializes and manages the lifecycle of other core components, providing a unified, high-level interface for accessing various Reddit resources. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit:57-901 `_ + +Authentication Manager +^^^^^^^^^^^^^^^^^^^^^^ + +Handles the setup and management of authentication with the Reddit API, supporting different OAuth flows and credential management. It configures the underlying HTTP client for authenticated requests. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit:_prepare_prawcore `_ +* `praw.reddit.Reddit:_prepare_untrusted_prawcore `_ +* `praw.reddit.Reddit:_prepare_trusted_prawcore `_ +* `praw.reddit.Reddit:_prepare_common_authorizer `_ + +HTTP Request Dispatcher +^^^^^^^^^^^^^^^^^^^^^^^ + +Manages the end-to-end process of sending API requests. This includes preparing the request, dispatching it to the Reddit API, and handling the raw HTTP response. It integrates with the Rate Limiting Handler and may manage asynchronous operations. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit:_objectify_request `_ +* `praw.reddit.Reddit:request `_ +* `praw.reddit.Reddit:_check_for_async `_ + +Response Object Mapper +^^^^^^^^^^^^^^^^^^^^^^ + +Transforms raw JSON responses received from the Reddit API into structured and usable Python objects (e.g., `Submission`, `Comment`, `Redditor`). This component abstracts away the complexities of JSON parsing and provides a consistent object-oriented view of Reddit data. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit:_prepare_objector `_ + +Resource Accessors +^^^^^^^^^^^^^^^^^^ + +Provides a set of high-level, Pythonic methods for interacting with specific Reddit resources and performing common operations (e.g., fetching submissions, comments, or user profiles; performing GET/POST/PUT/DELETE requests). It also includes functionality for resolving Reddit URLs and generating lists of resources. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit:delete `_ +* `praw.reddit.Reddit:get `_ +* `praw.reddit.Reddit:patch `_ +* `praw.reddit.Reddit:post `_ +* `praw.reddit.Reddit:put `_ +* `praw.reddit.Reddit:username_available `_ +* `praw.reddit.Reddit:comment `_ +* `praw.reddit.Reddit:submission `_ +* `praw.reddit.Reddit:info `_ +* `praw.reddit.Reddit:generator `_ +* `praw.reddit.Reddit:_resolve_share_url `_ + +Rate Limiting Handler +^^^^^^^^^^^^^^^^^^^^^ + +Monitors and enforces Reddit API rate limits. It pauses requests when necessary to prevent exceeding the allowed request frequency, ensuring compliance with API terms and preventing service interruptions. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit:_handle_rate_limit `_ diff --git a/docs/architecture_overview/Reddit_Data_Models.rst b/docs/architecture_overview/Reddit_Data_Models.rst new file mode 100644 index 000000000..d51b2750b --- /dev/null +++ b/docs/architecture_overview/Reddit_Data_Models.rst @@ -0,0 +1,102 @@ +Reddit Data Models +================== + +.. mermaid:: + + graph LR + praw_models_reddit_subreddit["praw.models.reddit.subreddit"] + praw_models_reddit_submission["praw.models.reddit.submission"] + praw_models_reddit_comment["praw.models.reddit.comment"] + praw_models_reddit_redditor["praw.models.reddit.redditor"] + praw_models_reddit_modmail["praw.models.reddit.modmail"] + praw_models_reddit_live["praw.models.reddit.live"] + praw_models_reddit_widgets["praw.models.reddit.widgets"] + praw_models_reddit_collections["praw.models.reddit.collections"] + praw_models_reddit_submission -- "retrieves associated" --> praw_models_reddit_comment + praw_models_reddit_comment -- "accesses the parent" --> praw_models_reddit_submission + +| |codeboarding-badge| |demo-badge| |contact-badge| + +.. |codeboarding-badge| image:: https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square + :target: https://github.com/CodeBoarding/CodeBoarding +.. |demo-badge| image:: https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square + :target: https://www.codeboarding.org/demo +.. |contact-badge| image:: https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square + :target: mailto:contact@codeboarding.org + +Details +------- + +The `Reddit Data Models` subsystem, rooted in `praw.models.reddit`, provides a structured, Pythonic interface to various Reddit entities, abstracting the underlying API interactions. It aligns with the project's goal of offering a clean API Wrapper/Client Library by defining distinct objects for different Reddit resources. + +praw.models.reddit.subreddit +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Manages subreddit properties, moderation, content submission, flair, styles, and user relationships. It serves as a central hub for all subreddit-specific operations. + +**Related Classes/Methods**: + +* `praw.models.reddit.subreddit `_ + +praw.models.reddit.submission +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Manages post details, flair, moderation, and comment retrieval. It encapsulates all functionalities related to a single Reddit post. + +**Related Classes/Methods**: + +* `praw.models.reddit.submission `_ + +praw.models.reddit.comment +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Handles comment moderation and navigation to its parent or submission. It provides an interface for interacting with individual comments. + +**Related Classes/Methods**: + +* `praw.models.reddit.comment `_ + +praw.models.reddit.redditor +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Manages user streams and friendship status. It provides an interface for interacting with Reddit user profiles. + +**Related Classes/Methods**: + +* `praw.models.reddit.redditor `_ + +praw.models.reddit.modmail +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Parses and manages modmail conversations, providing functionality for interacting with Reddit's internal moderation messaging system. + +**Related Classes/Methods**: + +* `praw.models.reddit.modmail `_ + +praw.models.reddit.live +^^^^^^^^^^^^^^^^^^^^^^^ + +Manages Live Threads, handling invites, updates, and contributions for real-time event streams. + +**Related Classes/Methods**: + +* `praw.models.reddit.live `_ + +praw.models.reddit.widgets +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Provides an interface for interacting with subreddit widgets, including moderation and creation of different widget types. + +**Related Classes/Methods**: + +* `praw.models.reddit.widgets `_ + +praw.models.reddit.collections +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Manages post collections within a subreddit, providing an interface for creating, modifying, and retrieving curated groups of posts. + +**Related Classes/Methods**: + +* `praw.models.reddit.collections `_ diff --git a/docs/architecture_overview/overview.rst b/docs/architecture_overview/overview.rst new file mode 100644 index 000000000..791a708b0 --- /dev/null +++ b/docs/architecture_overview/overview.rst @@ -0,0 +1,154 @@ +Overview +======== + +.. mermaid:: + + graph LR + Reddit_Client["Reddit Client"] + Configuration_Manager["Configuration Manager"] + Low_Level_API_Connector["Low-Level API Connector"] + Object_Transformer["Object Transformer"] + Reddit_Data_Models["Reddit Data Models"] + Listing_Streaming["Listing & Streaming"] + Unclassified["Unclassified"] + Unclassified["Unclassified"] + Unclassified["Unclassified"] + Unclassified["Unclassified"] + Unclassified["Unclassified"] + Unclassified["Unclassified"] + Reddit_Client -- "loads settings from" --> Configuration_Manager + Reddit_Client -- "delegates requests to" --> Low_Level_API_Connector + Low_Level_API_Connector -- "returns raw response to" --> Reddit_Client + Reddit_Client -- "sends raw data to" --> Object_Transformer + Object_Transformer -- "instantiates" --> Reddit_Data_Models + Reddit_Data_Models -- "initiates requests via" --> Reddit_Client + Listing_Streaming -- "fetches data via" --> Reddit_Client + Listing_Streaming -- "generates" --> Reddit_Data_Models + click Reddit_Client href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Reddit_Client.html" "Details" + click Configuration_Manager href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Configuration_Manager.html" "Details" + click Low_Level_API_Connector href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Low_Level_API_Connector.html" "Details" + click Object_Transformer href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Object_Transformer.html" "Details" + click Reddit_Data_Models href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Reddit_Data_Models.html" "Details" + click Listing_Streaming href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Listing_Streaming.html" "Details" + +| |codeboarding-badge| |demo-badge| |contact-badge| + +.. |codeboarding-badge| image:: https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square + :target: https://github.com/CodeBoarding/CodeBoarding +.. |demo-badge| image:: https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square + :target: https://www.codeboarding.org/demo +.. |contact-badge| image:: https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square + :target: mailto:contact@codeboarding.org + +Details +------- + +The PRAW library's architecture is centered around the Reddit Client, which acts as the primary orchestrator for all interactions with the Reddit API. This client relies on the Configuration Manager to load and manage its operational settings, ensuring proper initialization. For actual network communication and secure authentication, the Reddit Client delegates to the Low-Level API Connector (an external dependency, `prawcore`), which handles the intricacies of HTTP requests and OAuth2. Upon receiving raw JSON responses from the API via the Low-Level API Connector, the Reddit Client forwards this data to the Object Transformer. The Object Transformer is responsible for converting these raw responses into structured Python objects, which are instances of the Reddit Data Models (e.g., `Subreddit`, `Submission`). These data models represent the various entities within Reddit and can, in turn, initiate further requests through the Reddit Client to fetch related data. Complementing this core interaction, the Listing & Streaming component provides efficient mechanisms for iterating over collections of Reddit items, including real-time data streams, by fetching data through the Reddit Client and generating instances of the Reddit Data Models for consumption. This design ensures a clear separation of concerns, with the Reddit Client managing the overall flow, specialized components handling data transformation and retrieval, and a robust set of data models representing the API's entities. + +Reddit Client +^^^^^^^^^^^^^ + +:ref:`Expand ` + +The primary interface for interacting with the Reddit API, managing authentication and request dispatch. + +**Related Classes/Methods**: + +* `praw/reddit.py `_ + +Configuration Manager +^^^^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +Manages loading and accessing PRAW's configuration settings. + +**Related Classes/Methods**: + +* `praw/config.py `_ + +Low-Level API Connector +^^^^^^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +An external dependency responsible for actual HTTP communication and OAuth2 authentication with the Reddit API. + +**Related Classes/Methods**: + +* `prawcore:527-546 `_ + +Object Transformer +^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +Converts raw JSON data from the Reddit API into structured PRAW Python objects. + +**Related Classes/Methods**: + +* `praw/objector.py `_ + +Reddit Data Models +^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +A collection of classes representing various Reddit entities (e.g., `Subreddit`, `Submission`, `Comment`). + +**Related Classes/Methods**: + +* `praw.models.reddit `_ + +Listing & Streaming +^^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +Provides mechanisms for efficiently retrieving and iterating over collections of Reddit items, including real-time data streams. + +**Related Classes/Methods**: + +* `praw.models.listing `_ + +Unclassified +^^^^^^^^^^^^ + +Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies) + +**Related Classes/Methods**: *None* + +Unclassified +^^^^^^^^^^^^ + +Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies) + +**Related Classes/Methods**: *None* + +Unclassified +^^^^^^^^^^^^ + +Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies) + +**Related Classes/Methods**: *None* + +Unclassified +^^^^^^^^^^^^ + +Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies) + +**Related Classes/Methods**: *None* + +Unclassified +^^^^^^^^^^^^ + +Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies) + +**Related Classes/Methods**: *None* + +Unclassified +^^^^^^^^^^^^ + +Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies) + +**Related Classes/Methods**: *None* diff --git a/docs/conf.py b/docs/conf.py index bf6ef0511..cbb8322ea 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -14,6 +14,7 @@ "sphinx.ext.autodoc", "sphinx.ext.intersphinx", "sphinx_autodoc_typehints", + "sphinxcontrib.mermaid", ] html_theme = "furo" htmlhelp_basename = "PRAW" diff --git a/docs/index.rst b/docs/index.rst index 89ded731f..89cf28449 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,6 +5,7 @@ PRAW's documentation is organized into the following sections: - :ref:`getting_started` - :ref:`code_overview` +- :ref:`architecture_overview` - :ref:`tutorial` - :ref:`package_info` @@ -41,6 +42,19 @@ application. See :ref:`oauth` for information on using **installed** application code_overview/exceptions code_overview/other +.. _architecture_overview: + +.. toctree:: + :maxdepth: 1 + :caption: Architecture Overview + + architecture_overview/overview + architecture_overview/Listing_Streaming + architecture_overview/Low_Level_API_Connector + architecture_overview/Object_Transformer + architecture_overview/Reddit_Data_Models + architecture_overview/Reddit_Client + .. _tutorial: .. toctree:: diff --git a/pyproject.toml b/pyproject.toml index 8d0b841b6..19ff4286f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -57,7 +57,8 @@ lint = [ readthedocs = [ "furo", "sphinx", - "sphinx-autodoc-typehints" + "sphinx-autodoc-typehints", + "sphinxcontrib-mermaid" ] test = [ "betamax >=0.9, <0.10",