From fe29e217e006807e6c501b108c15e7a91c762961 Mon Sep 17 00:00:00 2001 From: ivanmilevtues Date: Tue, 10 Jun 2025 00:00:22 +0200 Subject: [PATCH 01/23] Added high-level diagrams --- .codeboarding/Content & Listing Management.md | 170 +++++++++++++++ .codeboarding/Development & Build Tools.md | 88 ++++++++ .codeboarding/PRAW Core & API Interaction.md | 133 ++++++++++++ .codeboarding/Reddit Data Models.md | 172 +++++++++++++++ .codeboarding/Specialized Content Features.md | 204 ++++++++++++++++++ .codeboarding/User & Community Management.md | 172 +++++++++++++++ .codeboarding/on_boarding.md | 190 ++++++++++++++++ 7 files changed, 1129 insertions(+) create mode 100644 .codeboarding/Content & Listing Management.md create mode 100644 .codeboarding/Development & Build Tools.md create mode 100644 .codeboarding/PRAW Core & API Interaction.md create mode 100644 .codeboarding/Reddit Data Models.md create mode 100644 .codeboarding/Specialized Content Features.md create mode 100644 .codeboarding/User & Community Management.md create mode 100644 .codeboarding/on_boarding.md diff --git a/.codeboarding/Content & Listing Management.md b/.codeboarding/Content & Listing Management.md new file mode 100644 index 000000000..df59a1bc1 --- /dev/null +++ b/.codeboarding/Content & Listing Management.md @@ -0,0 +1,170 @@ +```mermaid +graph LR + Reddit_Client["Reddit Client"] + Content_Listing_Management["Content & Listing Management"] + Listing_Generators["Listing Generators"] + Comment_Objects["Comment Objects"] + Submission_Objects["Submission Objects"] + Subreddit_Objects["Subreddit Objects"] + User_Objects["User Objects"] + Inbox_Manager["Inbox Manager"] + Draft_Management["Draft Management"] + Stream_Utilities["Stream Utilities"] + Listing_Mixins["Listing Mixins"] + Reddit_Client -- "Provides access to" --> Comment_Objects + Reddit_Client -- "Provides access to" --> Submission_Objects + Reddit_Client -- "Provides access to" --> Subreddit_Objects + Reddit_Client -- "Provides access to" --> User_Objects + Reddit_Client -- "Manages user inbox through" --> Inbox_Manager + Reddit_Client -- "Manages drafts through" --> Draft_Management + Reddit_Client -- "Provides access to" --> Content_Listing_Management + Content_Listing_Management -- "Uses" --> Listing_Generators + Content_Listing_Management -- "Manages" --> Comment_Objects + Content_Listing_Management -- "Manages" --> Submission_Objects + Content_Listing_Management -- "Uses" --> Listing_Mixins + Content_Listing_Management -- "Uses" --> Draft_Management + Content_Listing_Management -- "Uses" --> Stream_Utilities + Inbox_Manager -- "Uses for data retrieval" --> Listing_Generators + Listing_Mixins -- "Implements listings via" --> Listing_Generators + Stream_Utilities -- "Can consume output from" --> Listing_Generators + Comment_Objects -- "Forms hierarchical structures with" --> Comment_Objects + Submission_Objects -- "Contains comments" --> Comment_Objects + Subreddit_Objects -- "Receives submissions" --> Submission_Objects + Subreddit_Objects -- "Extends with listing features" --> Listing_Mixins + User_Objects -- "Enables streaming of user content" --> Stream_Utilities + Subreddit_Objects -- "Enables streaming of subreddit content" --> Stream_Utilities + Listing_Generators -- "Produces" --> Comment_Objects + Listing_Generators -- "Produces" --> Submission_Objects + Listing_Generators -- "Produces" --> User_Objects + Listing_Generators -- "Produces" --> Subreddit_Objects +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +This graph illustrates the architecture of the Content & Listing Management subsystem within the PRAW library, focusing on how it retrieves, iterates, and manages various types of Reddit content. The core functionality revolves around efficient listing generation and the handling of submissions, comments, and related data like drafts and polls. It interacts with the central Reddit Client for API access and leverages specialized components for listing generation, stream utilities, and specific Reddit object management. + +### Reddit Client +The central entry point for interacting with the Reddit API, managing authentication and providing access to various Reddit entities. + + +**Related Classes/Methods**: + +- `praw.praw.reddit.Reddit` (57:901) + + +### Content & Listing Management +Responsible for efficiently retrieving and iterating through various types of content listings from Reddit, such as hot, new, or top posts. It also provides utilities for real-time data streams and handles the creation, retrieval, and general management of Reddit submissions (posts) and comments, including drafts and poll data. + + +**Related Classes/Methods**: + +- `praw.praw.models.listing.generator.ListingGenerator` (17:103) +- `praw.praw.models.listing.domain.DomainListing` (14:25) +- `praw.praw.models.listing.mixins.redditor.SubListing` (18:32) +- `praw.praw.models.listing.mixins.redditor.RedditorListingMixin` (35:185) +- `praw.praw.models.listing.mixins.subreddit.CommentHelper` (20:46) +- `praw.praw.models.listing.mixins.subreddit.SubredditListingMixin` (49:73) +- `praw.praw.models.listing.mixins.rising.RisingListingMixin` (17:34) +- `praw.praw.models.listing.mixins.base.BaseListingMixin` (15:149) +- `praw.praw.models.listing.mixins.submission.SubmissionListingMixin` (17:42) +- `praw.praw.models.util` (10:190) +- `praw.praw.models.comment_forest.CommentForest` (15:202) +- `praw.praw.models.reddit.comment.Comment` (19:311) +- `praw.praw.models.reddit.comment.CommentModeration` (314:350) +- `praw.praw.models.reddit.more.MoreComments` (14:87) +- `praw.praw.models.reddit.submission.Submission` (395:916) +- `praw.praw.models.reddit.submission.SubmissionFlair` (40:90) +- `praw.praw.models.reddit.submission.SubmissionModeration` (93:392) +- `praw.praw.models.helpers.DraftHelper` (20:133) +- `praw.praw.models.reddit.draft.Draft` (17:292) +- `praw.praw.models.reddit.poll.PollData` (47:112) +- `praw.praw.models.reddit.poll.PollOption` (11:44) + + +### Listing Generators +A core component responsible for iterating and fetching paginated lists of various Reddit objects. + + +**Related Classes/Methods**: + +- `praw.models.listing.generator.ListingGenerator` (17:103) + + +### Comment Objects +Represents individual Reddit comments, providing methods for interaction and retrieval of related data. + + +**Related Classes/Methods**: + +- `praw.praw.models.reddit.comment.Comment` (19:311) + + +### Submission Objects +Represents Reddit posts (submissions), offering functionalities for content manipulation and moderation. + + +**Related Classes/Methods**: + +- `praw.praw.models.reddit.submission.Submission` (395:916) + + +### Subreddit Objects +Represents Reddit communities (subreddits), enabling content submission and moderation within them. + + +**Related Classes/Methods**: + +- `praw.praw.models.reddit.subreddit.Subreddit` (full file reference) + + +### User Objects +Represents Reddit user accounts, providing access to user-specific content and profiles. + + +**Related Classes/Methods**: + +- `praw.praw.models.reddit.redditor.Redditor` (21:409) + + +### Inbox Manager +Manages the authenticated user's Reddit inbox, allowing retrieval of messages, comment replies, and mentions. + + +**Related Classes/Methods**: + +- `praw.praw.models.inbox.Inbox` (18:324) + + +### Draft Management +Provides utilities for creating and managing submission drafts. + + +**Related Classes/Methods**: + +- `praw.praw.models.helpers.DraftHelper` (20:133) + + +### Stream Utilities +Offers helper functions for continuously streaming new Reddit content, such as comments or submissions. + + +**Related Classes/Methods**: + +- `praw.praw.models.util.stream_generator` (36:163) + + +### Listing Mixins +Abstract classes providing common methods for fetching various types of listings (e.g., hot, new, top) across different Reddit entities. + + +**Related Classes/Methods**: + +- `praw.praw.models.listing.mixins.base.BaseListingMixin` (15:149) +- `praw.praw.models.listing.mixins.redditor.RedditorListingMixin` (35:185) +- `praw.praw.models.listing.mixins.subreddit.SubredditListingMixin` (49:73) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Development & Build Tools.md b/.codeboarding/Development & Build Tools.md new file mode 100644 index 000000000..12e4a3c53 --- /dev/null +++ b/.codeboarding/Development & Build Tools.md @@ -0,0 +1,88 @@ +```mermaid +graph LR + Pre_Push_Automation["Pre-Push Automation"] + Static_Word_Checks["Static Word Checks"] + Documentation_Checks["Documentation Checks"] + Active_Documentation_Management["Active Documentation Management"] + Version_Management["Version Management"] + Pre_Push_Automation -- "orchestrates" --> Static_Word_Checks + Pre_Push_Automation -- "orchestrates" --> Documentation_Checks + Pre_Push_Automation -- "utilizes" --> Version_Management +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +This component comprises scripts and utilities primarily used for the development, testing, and release management of the PRAW library itself. It includes tools for static analysis, unit testing, and version control, and is not part of the library's runtime functionality. + +### Pre-Push Automation +This component automates pre-push checks, including running static analysis (pre-commit, sphinx-build) and unit tests (pytest). It orchestrates the execution of these checks and reports their success or failure. + + +**Related Classes/Methods**: + +- `praw.pre_push` (2:80) +- `praw.pre_push.main` (58:98) +- `praw.pre_push.run_static` (32:45) +- `praw.pre_push.run_unit` (48:55) +- `praw.pre_push.do_process` (10:29) + + +### Static Word Checks +This component is responsible for performing static analysis on the codebase, specifically checking for double syntax and 'noreturn' patterns within the code. It uses a dedicated checker class to encapsulate this logic. + + +**Related Classes/Methods**: + +- `praw.tools.static_word_checks` (5:100) +- `praw.tools.static_word_checks.main` (120:140) +- `praw.tools.static_word_checks.StaticChecker` (8:117) +- `praw.tools.static_word_checks.StaticChecker.run_checks` (75:117) +- `praw.tools.static_word_checks.StaticChecker.check_for_double_syntax` (27:55) +- `praw.tools.static_word_checks.StaticChecker.check_for_noreturn` (57:73) + + +### Documentation Checks +This component focuses on verifying the documentation, particularly by discovering and checking subclasses for proper documentation. It ensures consistency and completeness of the project's documentation. + + +**Related Classes/Methods**: + +- `praw.tools.check_documentation` (5:70) +- `praw.tools.check_documentation.main` (80:81) +- `praw.tools.check_documentation.DocumentationChecker` (16:77) +- `praw.tools.check_documentation.DocumentationChecker.check` (46:77) +- `praw.tools.check_documentation.DocumentationChecker.discover_subclasses` (36:43) + + +### Active Documentation Management +This component manages the active documentation versions, primarily by fetching available versions. It likely supports processes related to deploying or updating documentation. + + +**Related Classes/Methods**: + +- `praw.tools.set_active_docs` (5:80) +- `praw.tools.set_active_docs.main` (32:90) +- `praw.tools.set_active_docs.fetch_versions` (14:29) + + +### Version Management +This component handles the project's versioning, including managing unreleased changes, updating the changelog, incrementing development versions, and updating package version information. It ensures proper version control and release preparation. + + +**Related Classes/Methods**: + +- `praw.tools.set_version` (5:100) +- `praw.tools.set_version.main` (64:70) +- `praw.tools.set_version.handle_unreleased` (32:33) +- `praw.tools.set_version.handle_version` (36:40) +- `praw.tools.set_version.add_unreleased_to_changelog` (15:29) +- `praw.tools.set_version.increment_development_version` (43:61) +- `praw.tools.set_version.valid_version` (107:112) +- `praw.tools.set_version.update_changelog` (73:88) +- `praw.tools.set_version.update_package` (91:104) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/PRAW Core & API Interaction.md b/.codeboarding/PRAW Core & API Interaction.md new file mode 100644 index 000000000..76bef443a --- /dev/null +++ b/.codeboarding/PRAW Core & API Interaction.md @@ -0,0 +1,133 @@ +```mermaid +graph LR + RedditClientCore["RedditClientCore"] + ObjectTransformationLayer["ObjectTransformationLayer"] + ConfigurationManagement["ConfigurationManagement"] + ExceptionHandling["ExceptionHandling"] + UtilityFunctions["UtilityFunctions"] + RedditClientCore -- "loads configuration from" --> ConfigurationManagement + RedditClientCore -- "accesses settings from" --> ConfigurationManagement + RedditClientCore -- "uses for objectification" --> ObjectTransformationLayer + RedditClientCore -- "initializes" --> ObjectTransformationLayer + RedditClientCore -- "raises" --> ExceptionHandling + RedditClientCore -- "handles" --> ExceptionHandling + ObjectTransformationLayer -- "raises" --> ExceptionHandling + ObjectTransformationLayer -- "parses errors using" --> ExceptionHandling + ObjectTransformationLayer -- "uses for key conversion" --> UtilityFunctions + ConfigurationManagement -- "raises" --> ExceptionHandling +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +This graph represents the core interaction layer of the PRAW library with the Reddit API. The main flow involves the `RedditClientCore` initiating API requests, which are then processed by the `ObjectTransformationLayer` to convert raw responses into structured Python objects. `ConfigurationManagement` provides necessary settings for the client, while `ExceptionHandling` ensures robust error management across these interactions. `UtilityFunctions` support various operations, including data transformation for consistency. + +### RedditClientCore +This component serves as the central interface for interacting with the Reddit API. It manages the lifecycle of API interactions, including initialization, authentication, and dispatching various types of HTTP requests (GET, POST, PUT, DELETE, PATCH). It also integrates with other components to handle objectification of responses, rate limiting, and update checks, providing a comprehensive entry point for PRAW users. + + +**Related Classes/Methods**: + +- `praw.praw.reddit.Reddit` (57:901) +- `praw.praw.reddit.Reddit:read_only` (87:89) +- `praw.praw.reddit.Reddit:__init__` (114:386) +- `praw.praw.reddit.Reddit:_objectify_request` (435:469) +- `praw.praw.reddit.Reddit:_prepare_objector` (479:525) +- `praw.praw.reddit.Reddit:_prepare_prawcore` (527:546) +- `praw.praw.reddit.Reddit:_prepare_trusted_prawcore` (548:564) +- `praw.praw.reddit.Reddit:_prepare_untrusted_prawcore` (566:570) +- `praw.praw.reddit.Reddit:_resolve_share_url` (572:580) +- `praw.praw.reddit.Reddit:comment` (582:596) +- `praw.praw.reddit.Reddit:delete` (598:617) +- `praw.praw.reddit.Reddit:domain` (619:625) +- `praw.praw.reddit.Reddit:get` (627:639) +- `praw.praw.reddit.Reddit:info` (641:720) +- `praw.praw.reddit.Reddit:patch` (722:741) +- `praw.praw.reddit.Reddit:post` (743:789) +- `praw.praw.reddit.Reddit:put` (791:808) +- `praw.praw.reddit.Reddit:redditor` (810:819) +- `praw.praw.reddit.Reddit:request` (821:876) +- `praw.praw.reddit.Reddit:submission` (878:889) +- `praw.praw.reddit.Reddit:username_available` (891:901) +- `praw.praw.reddit.Reddit._check_for_update` (413:418) +- `praw.praw.reddit.Reddit._check_for_async` (388:411) +- `praw.praw.reddit.Reddit._handle_rate_limit` (420:433) +- `praw.praw.reddit.Reddit._prepare_common_authorizer` (471:477) +- `praw.models.auth.Auth` (11:125) +- `praw.models.helpers.DraftHelper` (20:133) +- `praw.models.front.Front` (17:32) +- `praw.models.inbox.Inbox` (18:324) +- `praw.models.helpers.LiveHelper` (136:238) +- `praw.models.helpers.MultiredditHelper` (241:298) +- `praw.models.mod_notes.RedditModNotes` (466:682) +- `praw.models.redditors.Redditors` (26:104) +- `praw.models.helpers.SubredditHelper` (301:353) +- `praw.models.subreddits.Subreddits` (19:133) +- `praw.models.user.User` (24:259) +- `praw.models.reddit.comment.Comment` (19:311) +- `praw.models.listing.domain.DomainListing` (14:25) +- `praw.models.reddit.redditor.Redditor` (21:409) +- `praw.models.reddit.submission.Submission` (395:916) + + +### ObjectTransformationLayer +This component is responsible for transforming raw JSON responses received from the Reddit API into structured Python objects that PRAW users can easily interact with. It also includes functionality for parsing and handling API-specific errors embedded within the responses and converting dictionary keys from camelCase to snake_case for Pythonic consistency. + + +**Related Classes/Methods**: + +- `praw.praw.objector.Objector` (17:263) +- `praw.praw.objector.Objector:check_error` (21:24) +- `praw.praw.objector.Objector:parse_error` (27:48) +- `praw.praw.objector.Objector:_objectify_dict` (59:201) +- `praw.praw.objector.Objector:objectify` (203:263) + + +### ConfigurationManagement +This component is dedicated to loading, managing, and providing access to PRAW's configuration settings. It supports reading configurations from various sources, such as a 'praw.ini' file or environment variables, ensuring that the Reddit client is properly configured with necessary credentials and API parameters. + + +**Related Classes/Methods**: + +- `praw.praw.config.Config` (27:173) +- `praw.praw.config.Config:short_url` (74:83) +- `praw.praw.config.Config:__init__` (85:103) +- `praw.praw.config.Config:_fetch_default` (110:113) +- `praw.praw.config.Config:_fetch_or_not_set` (115:123) +- `praw.praw.config.Config:_initialize_attributes` (125:173) +- `praw.praw.config.Config:_load_config` (45:71) +- `praw.praw.config.Config:_config_boolean` (39:42) +- `praw.praw.config.Config:_fetch` (105:108) + + +### ExceptionHandling +This component centralizes the definition and management of custom exceptions within PRAW. It provides a structured way to handle various error conditions, including client-side issues, Reddit API errors, and specific operational failures like media post failures or missing attributes, ensuring robust error reporting and recovery. + + +**Related Classes/Methods**: + +- `praw.praw.exceptions.MediaPostFailed` (158:167) +- `praw.praw.exceptions.RedditAPIException` (170:201) +- `praw.praw.exceptions.ClientException` (74:75) +- `praw.praw.exceptions.MissingRequiredAttributeException` (121:122) +- `praw.praw.exceptions.RedditAPIException:parse_exception_list` (174:189) +- `praw.praw.exceptions.RedditAPIException:__init__` (191:201) +- `praw.praw.exceptions.RedditErrorItem` (18:71) +- `praw.praw.exceptions.MediaPostFailed:__init__` (161:167) +- `praw.praw.exceptions.WebSocketException.__init__` (149:155) + + +### UtilityFunctions +This component provides a collection of general-purpose utility functions that support various operations within PRAW. Specifically, it includes functions for string manipulation, such as converting dictionary keys from camelCase to snake_case, which is crucial for maintaining consistent naming conventions across the library's object model. + + +**Related Classes/Methods**: + +- `praw.praw.util.snake` (6:19) +- `praw.praw.util.snake:snake_case_keys` (16:22) +- `praw.praw.util.snake:camel_to_snake` (11:13) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Reddit Data Models.md b/.codeboarding/Reddit Data Models.md new file mode 100644 index 000000000..98b4f9d92 --- /dev/null +++ b/.codeboarding/Reddit Data Models.md @@ -0,0 +1,172 @@ +```mermaid +graph LR + PRAWBase_Component["PRAWBase Component"] + RedditBase_Component["RedditBase Component"] + Listing_Generation_Component["Listing Generation Component"] + Listing_Mixins_Component["Listing Mixins Component"] + Subreddit_Management_Component["Subreddit Management Component"] + Comment_Management_Component["Comment Management Component"] + Submission_Management_Component["Submission Management Component"] + Voting_Mechanism_Component["Voting Mechanism Component"] + Moderation_Mixin_Component["Moderation Mixin Component"] + Base_List_Component["Base List Component"] + RedditBase_Component -- "inherits from" --> PRAWBase_Component + Listing_Generation_Component -- "inherits from" --> PRAWBase_Component + Base_List_Component -- "inherits from" --> PRAWBase_Component + Subreddit_Management_Component -- "inherits from" --> RedditBase_Component + Comment_Management_Component -- "inherits from" --> RedditBase_Component + Submission_Management_Component -- "inherits from" --> RedditBase_Component + Listing_Mixins_Component -- "utilizes" --> Listing_Generation_Component + Listing_Mixins_Component -- "depends on" --> PRAWBase_Component + Subreddit_Management_Component -- "utilizes" --> Listing_Generation_Component + Voting_Mechanism_Component -- "applies to" --> RedditBase_Component + Moderation_Mixin_Component -- "applies to" --> RedditBase_Component + Moderation_Mixin_Component -- "provides moderation to" --> Comment_Management_Component + Moderation_Mixin_Component -- "provides moderation to" --> Submission_Management_Component +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +This graph provides an overview of the Reddit Data Models subsystem in PRAW, which defines the foundational structure and common behaviors for various Reddit entities. It illustrates how core base classes like PRAWBase and RedditBase establish the blueprint for data representation, while specialized components manage specific Reddit objects such as subreddits, comments, and submissions. Mixin components integrate common functionalities like voting, moderation, and listing generation across different data models, ensuring consistent interaction with the Reddit API and efficient data handling. + +### PRAWBase Component +This component serves as the foundational superclass for all models within the PRAW library. It provides core utilities such as safely adding arguments to dictionaries and a class method for parsing data into PRAWBase instances. It initializes instances with a Reddit object and optional initial data. + + +**Related Classes/Methods**: + +- `praw.models.base.PRAWBase` (12:47) +- `praw.models.base.PRAWBase._safely_add_arguments` (16:26) +- `praw.models.base.PRAWBase.parse` (29:36) +- `praw.models.base.PRAWBase.__init__` (38:47) + + +### RedditBase Component +Building upon PRAWBase, this component represents actual Reddit objects. It includes functionalities for parsing URLs, handling attribute access (fetching data if not already fetched), and defining equality/hashing for Reddit objects. It also provides methods for fetching data from the Reddit API and resetting attributes. + + +**Related Classes/Methods**: + +- `praw.models.reddit.base.RedditBase` (16:90) +- `praw.models.reddit.base.RedditBase._url_parts` (20:24) +- `praw.models.reddit.base.RedditBase.__getattr__` (32:38) +- `praw.models.reddit.base.RedditBase.__init__` (44:64) +- `praw.models.reddit.base.RedditBase._fetch` (78:79) +- `praw.models.reddit.base.RedditBase._fetch_data` (81:84) +- `praw.models.reddit.base.RedditBase._reset_attributes` (86:90) + + +### Listing Generation Component +This component is responsible for generating and iterating through various Reddit listings, such as comments, submissions, or other content. It manages the fetching of batches of items from the Reddit API and handles pagination to provide a continuous stream of content. + + +**Related Classes/Methods**: + +- `praw.models.listing.generator.ListingGenerator` (17:103) +- `praw.models.listing.generator.ListingGenerator.__init__` (29:56) +- `praw.models.listing.generator.ListingGenerator.__iter__` (58:60) +- `praw.models.listing.generator.ListingGenerator.__next__` (62:73) +- `praw.models.listing.generator.ListingGenerator._extract_sublist` (75:87) +- `praw.models.listing.generator.ListingGenerator._next_batch` (89:103) + + +### Listing Mixins Component +This component provides a set of mixin classes that add common listing functionalities to various Reddit objects. It includes methods for retrieving controversial, hot, new, and top items, with support for time filters and argument preparation for API requests. + + +**Related Classes/Methods**: + +- `praw.models.listing.mixins.base.BaseListingMixin` (15:149) +- `praw.models.listing.mixins.base.BaseListingMixin._validate_time_filter` (21:30) +- `praw.models.listing.mixins.base.BaseListingMixin._prepare` (32:37) +- `praw.models.listing.mixins.base.BaseListingMixin.controversial` (39:72) +- `praw.models.listing.mixins.base.BaseListingMixin.hot` (74:94) +- `praw.models.listing.mixins.base.BaseListingMixin.new` (96:116) +- `praw.models.listing.mixins.base.BaseListingMixin.top` (118:149) + + +### Subreddit Management Component +This component encapsulates functionalities related to managing subreddits, including retrieving subreddit information, moderating content, and handling subreddit-specific streams like comments and submissions. It also provides methods for managing subreddit relationships and stylesheets. + + +**Related Classes/Methods**: + +- `praw.models.reddit.subreddit.Subreddit` (full file reference) +- `praw.models.reddit.subreddit.Subreddit.__init__` (full file reference) +- `praw.models.reddit.subreddit.Subreddit._fetch` (full file reference) +- `praw.models.reddit.subreddit.Subreddit.search` (full file reference) +- `praw.models.reddit.subreddit.SubredditModeration.log` (full file reference) +- `praw.models.reddit.subreddit.SubredditModeration.unmoderated` (full file reference) +- `praw.models.reddit.subreddit.SubredditStream.comments` (full file reference) +- `praw.models.reddit.subreddit.SubredditStream.submissions` (full file reference) + + +### Comment Management Component +This component handles operations related to Reddit comments. It provides methods for initializing comment instances, extracting comment IDs from URLs, accessing comment replies, and refreshing comment attributes. It also includes moderation functionalities specific to comments. + + +**Related Classes/Methods**: + +- `praw.models.reddit.comment.Comment` (19:311) +- `praw.models.reddit.comment.Comment.id_from_url` (64:74) +- `praw.models.reddit.comment.Comment.__init__` (143:163) +- `praw.models.reddit.comment.Comment._fetch` (185:196) +- `praw.models.reddit.comment.Comment.parent` (201:262) +- `praw.models.reddit.comment.Comment.refresh` (264:311) +- `praw.models.reddit.comment.CommentModeration.show` (336:350) + + +### Submission Management Component +This component manages Reddit submissions, providing functionalities for creating, retrieving, and moderating submissions. It includes methods for handling submission flair, setting contest mode, marking content as NSFW or spoiler, and managing sticky posts. + + +**Related Classes/Methods**: + +- `praw.models.reddit.submission.Submission` (395:916) +- `praw.models.reddit.submission.Submission.id_from_url` (452:483) +- `praw.models.reddit.submission.Submission.__init__` (566:598) +- `praw.models.reddit.submission.Submission._fetch` (710:723) +- `praw.models.reddit.submission.SubmissionModeration.contest_mode` (115:137) +- `praw.models.reddit.submission.SubmissionModeration.flair` (139:174) +- `praw.models.reddit.submission.SubmissionModeration.nsfw` (176:194) +- `praw.models.reddit.submission.SubmissionModeration.spoiler` (244:262) +- `praw.models.reddit.submission.SubmissionModeration.sticky` (264:297) + + +### Voting Mechanism Component +This component provides the core functionality for users to interact with the voting system on Reddit content. It allows for upvoting, downvoting, and clearing votes on various votable objects like submissions and comments. + + +**Related Classes/Methods**: + +- `praw.models.reddit.mixins.votable.VotableMixin` (8:92) +- `praw.models.reddit.mixins.votable.VotableMixin._vote` (11:12) +- `praw.models.reddit.mixins.votable.VotableMixin.clear_vote` (14:36) +- `praw.models.reddit.mixins.votable.VotableMixin.downvote` (38:64) +- `praw.models.reddit.mixins.votable.VotableMixin.upvote` (66:92) + + +### Moderation Mixin Component +This component provides a set of common moderation functionalities that can be applied to various 'Thing' objects (like comments and submissions) on Reddit. It includes methods for removing content and distinguishing posts. + + +**Related Classes/Methods**: + +- `praw.models.reddit.mixins.thing_moderation.ThingModerationMixin` (10:120) +- `praw.models.reddit.mixins.thing_moderation.ThingModerationMixin.remove` (full file reference) +- `praw.models.reddit.mixins.thing_moderation.ThingModerationMixin.undistinguish` (full file reference) + + +### Base List Component +This component provides the foundational structure for various list-like objects within PRAW, such as lists of drafts, moderated items, redditors, or trophies. It extends `PRAWBase` to offer common functionalities for managing collections of Reddit entities. + + +**Related Classes/Methods**: + +- `praw.models.list.base.BaseList` (15:54) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Specialized Content Features.md b/.codeboarding/Specialized Content Features.md new file mode 100644 index 000000000..4927e5414 --- /dev/null +++ b/.codeboarding/Specialized Content Features.md @@ -0,0 +1,204 @@ +```mermaid +graph LR + Reddit_Client["Reddit Client"] + Live_Thread_System["Live Thread System"] + Multireddit_System["Multireddit System"] + Collection_System["Collection System"] + Base_API_Models["Base API Models"] + Content_Listing_Streaming["Content Listing & Streaming"] + Reddit_Entities["Reddit Entities"] + Exception_Handling["Exception Handling"] + Specialized_Content_Features["Specialized Content Features"] + Reddit_Client -- "initializes helpers for" --> Live_Thread_System + Reddit_Client -- "initializes helpers for" --> Multireddit_System + Reddit_Client -- "initializes helpers for" --> Collection_System + Reddit_Client -- "utilizes" --> Base_API_Models + Reddit_Client -- "creates instances of" --> Reddit_Entities + Reddit_Client -- "handles" --> Exception_Handling + Live_Thread_System -- "inherits from" --> Base_API_Models + Live_Thread_System -- "generates" --> Content_Listing_Streaming + Multireddit_System -- "inherits from" --> Base_API_Models + Multireddit_System -- "streams content via" --> Content_Listing_Streaming + Collection_System -- "inherits from" --> Base_API_Models + Collection_System -- "manages" --> Reddit_Entities + Content_Listing_Streaming -- "produces" --> Reddit_Entities + Specialized_Content_Features -- "encompasses" --> Live_Thread_System + Specialized_Content_Features -- "encompasses" --> Multireddit_System + Specialized_Content_Features -- "encompasses" --> Collection_System +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +This graph illustrates the architecture of the PRAW library, focusing on how it manages various Reddit functionalities. The core `Reddit Client` component acts as the central entry point, handling API interactions and initializing helpers for specialized content types. These specialized content types, including `Live Thread System`, `Multireddit System`, and `Collection System`, are encapsulated within the `Specialized Content Features` component, providing dedicated interfaces for their unique structures and functionalities. All these systems leverage `Base API Models` for fundamental operations and interact with `Reddit Entities` to represent core Reddit objects. `Content Listing & Streaming` provides mechanisms for iterating and streaming data, while `Exception Handling` ensures robust error management across the library. + +### Reddit Client +The central class for interacting with the Reddit API, responsible for initialization, configuration, request handling, and providing access to various Reddit entities. + + +**Related Classes/Methods**: + +- `praw.reddit.Reddit` (57:901) +- `praw.reddit.Reddit.__init__` (114:386) +- `praw.reddit.Reddit._objectify_request` (435:469) +- `praw.reddit.Reddit.request` (821:876) +- `praw.reddit.Reddit.info` (641:720) +- `praw.reddit.Reddit.post` (743:789) +- `praw.reddit.Reddit.get` (627:639) +- `praw.reddit.Reddit.delete` (598:617) +- `praw.reddit.Reddit.patch` (722:741) +- `praw.reddit.Reddit.put` (791:808) +- `praw.reddit.Reddit.comment` (582:596) +- `praw.reddit.Reddit.domain` (619:625) +- `praw.reddit.Reddit.redditor` (810:819) +- `praw.reddit.Reddit.submission` (878:889) +- `praw.reddit.Reddit.username_available` (891:901) + + +### Live Thread System +This system encompasses all functionalities related to Reddit Live Threads, including their creation, retrieval, updates, contributor management, and streaming of live content. + + +**Related Classes/Methods**: + +- `praw.models.helpers.LiveHelper` (136:238) +- `praw.models.helpers.LiveHelper.__call__` (139:151) +- `praw.models.helpers.LiveHelper.info` (183:223) +- `praw.models.reddit.live.LiveThread` (261:471) +- `praw.models.reddit.live.LiveThread.__init__` (375:392) +- `praw.models.reddit.live.LiveThread._fetch` (394:399) +- `praw.models.reddit.live.LiveThread.contrib` (284:295) +- `praw.models.reddit.live.LiveThread.contributor` (298:313) +- `praw.models.reddit.live.LiveThread.stream` (316:338) +- `praw.models.reddit.live.LiveThread.__getitem__` (352:369) +- `praw.models.reddit.live.LiveThread.discussions` (404:426) +- `praw.models.reddit.live.LiveThread.updates` (446:471) +- `praw.models.reddit.live.LiveContributorRelationship` (22:258) +- `praw.models.reddit.live.LiveContributorRelationship.invite` (73:111) +- `praw.models.reddit.live.LiveContributorRelationship.update` (174:215) +- `praw.models.reddit.live.LiveContributorRelationship.update_invite` (217:258) +- `praw.models.reddit.live.LiveThreadContribution` (474:582) +- `praw.models.reddit.live.LiveThreadContribution.update` (523:582) +- `praw.models.reddit.live.LiveUpdate` (700:792) +- `praw.models.reddit.live.LiveUpdate.__init__` (743:780) +- `praw.models.reddit.live.LiveUpdate._fetch` (788:792) +- `praw.models.reddit.live.LiveUpdate.contrib` (724:736) +- `praw.models.reddit.live.LiveUpdate.__setattr__` (782:786) +- `praw.models.reddit.live.LiveThreadStream` (585:637) +- `praw.models.reddit.live.LiveThreadStream.updates` (605:637) + + +### Multireddit System +This system manages Reddit Multireddits, providing functionalities for creating, modifying, and retrieving multireddit content, as well as streaming from them. + + +**Related Classes/Methods**: + +- `praw.models.helpers.MultiredditHelper` (241:298) +- `praw.models.helpers.MultiredditHelper.__call__` (244:253) +- `praw.models.reddit.multi.Multireddit` (20:228) +- `praw.models.reddit.multi.Multireddit.__init__` (96:104) +- `praw.models.reddit.multi.Multireddit._fetch` (106:111) +- `praw.models.reddit.multi.Multireddit.add` (120:135) +- `praw.models.reddit.multi.Multireddit.copy` (137:161) +- `praw.models.reddit.multi.Multireddit.remove` (176:191) +- `praw.models.reddit.multi.Multireddit.stream` (72:94) +- `praw.models.reddit.multi.Multireddit.sluggify` (55:69) + + +### Collection System +This system handles Reddit Collections, including their creation, content management, and moderation functionalities. + + +**Related Classes/Methods**: + +- `praw.models.reddit.collections.Collection` (380:575) +- `praw.models.reddit.collections.Collection.__init__` (454:484) +- `praw.models.reddit.collections.Collection._fetch` (521:534) +- `praw.models.reddit.collections.Collection.mod` (422:438) +- `praw.models.reddit.collections.SubredditCollections` (291:377) +- `praw.models.reddit.collections.SubredditCollections.__init__` (352:360) +- `praw.models.reddit.collections.SubredditCollections.__call__` (316:350) +- `praw.models.reddit.collections.SubredditCollections.mod` (303:314) +- `praw.models.reddit.collections.CollectionModeration` (21:216) +- `praw.models.reddit.collections.CollectionModeration.__init__` (32:39) +- `praw.models.reddit.collections.CollectionModeration.add_post` (61:84) +- `praw.models.reddit.collections.CollectionModeration.remove_post` (102:125) +- `praw.models.reddit.collections.CollectionModeration.reorder` (127:147) +- `praw.models.reddit.collections.CollectionModeration._post_fullname` (41:59) +- `praw.models.reddit.collections.SubredditCollectionsModeration` (219:288) +- `praw.models.reddit.collections.SubredditCollectionsModeration.__init__` (230:238) + + +### Base API Models +This component provides the fundamental building blocks and common methods for various PRAW models, such as base initialization, URL parsing, and generic data fetching mechanisms. + + +**Related Classes/Methods**: + +- `praw.models.base.PRAWBase` (12:47) +- `praw.models.base.PRAWBase.__init__` (38:47) +- `praw.models.reddit.base.RedditBase` (16:90) +- `praw.models.reddit.base.RedditBase.__init__` (44:64) +- `praw.models.reddit.base.RedditBase._url_parts` (20:24) +- `praw.models.reddit.base.RedditBase._fetch_data` (81:84) +- `praw.models.reddit.base.RedditBase._fetch` (78:79) +- `praw.models.reddit.base.RedditBase._reset_attributes` (86:90) +- `praw.models.listing.mixins.subreddit.SubredditListingMixin` (49:73) +- `praw.models.listing.mixins.subreddit.SubredditListingMixin.__init__` (67:73) + + +### Content Listing & Streaming +This component is responsible for generating iterable listings of Reddit content and providing mechanisms for streaming real-time data from various sources. + + +**Related Classes/Methods**: + +- `praw.models.listing.generator.ListingGenerator` (17:103) +- `praw.models.util.stream_generator` (36:163) +- `praw.models.reddit.subreddit.SubredditStream` (full file reference) + + +### Reddit Entities +This component represents core Reddit entities such as Redditors (users) and Subreddits, encapsulating their properties and providing methods for interaction. + + +**Related Classes/Methods**: + +- `praw.models.reddit.redditor.Redditor` (21:409) +- `praw.models.reddit.subreddit.Subreddit` (full file reference) + + +### Exception Handling +This component defines and manages custom exceptions specific to the PRAW library, allowing for structured error handling within the application. + + +**Related Classes/Methods**: + +- `praw.exceptions.ClientException` (74:75) + + +### Specialized Content Features +Manages specialized content types on Reddit, including Live Threads, Multireddits, and Collections. It provides dedicated interfaces for interacting with these unique content structures and their specific functionalities. + + +**Related Classes/Methods**: + +- `praw.models.helpers.LiveHelper` (136:238) +- `praw.models.reddit.live.LiveContributorRelationship` (22:258) +- `praw.models.reddit.live.LiveThread` (261:471) +- `praw.models.reddit.live.LiveThreadContribution` (474:582) +- `praw.models.reddit.live.LiveThreadStream` (585:637) +- `praw.models.reddit.live.LiveUpdate` (700:792) +- `praw.models.reddit.live.LiveUpdateContribution` (640:697) +- `praw.models.helpers.MultiredditHelper` (241:298) +- `praw.models.reddit.multi.Multireddit` (20:228) +- `praw.models.reddit.collections.CollectionModeration` (21:216) +- `praw.models.reddit.collections.SubredditCollectionsModeration` (219:288) +- `praw.models.reddit.collections.SubredditCollections` (291:377) +- `praw.models.reddit.collections.Collection` (380:575) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/User & Community Management.md b/.codeboarding/User & Community Management.md new file mode 100644 index 000000000..9b62cc9b0 --- /dev/null +++ b/.codeboarding/User & Community Management.md @@ -0,0 +1,172 @@ +```mermaid +graph LR + RedditClientCore["RedditClientCore"] + UserAccountManagement["UserAccountManagement"] + RedditorInteraction["RedditorInteraction"] + SubredditManagement["SubredditManagement"] + ModerationTools["ModerationTools"] + SubredditWidgets["SubredditWidgets"] + ModmailConversations["ModmailConversations"] + SubredditContentManagement["SubredditContentManagement"] + ContentListingAndStreaming["ContentListingAndStreaming"] + RedditClientCore -- "initializes" --> UserAccountManagement + RedditClientCore -- "provides access to" --> UserAccountManagement + RedditClientCore -- "provides access to" --> RedditorInteraction + RedditClientCore -- "provides access to" --> SubredditManagement + RedditClientCore -- "provides access to" --> ModerationTools + UserAccountManagement -- "generates listings for" --> ContentListingAndStreaming + UserAccountManagement -- "interacts with" --> RedditorInteraction + RedditorInteraction -- "generates streams for" --> ContentListingAndStreaming + RedditorInteraction -- "is subject to moderation notes from" --> ModerationTools + SubredditManagement -- "generates streams for" --> ContentListingAndStreaming + SubredditManagement -- "is managed by" --> ModerationTools + SubredditManagement -- "manages" --> SubredditWidgets + SubredditManagement -- "handles modmail for" --> ModmailConversations + SubredditManagement -- "manages content aspects for" --> SubredditContentManagement + ModerationTools -- "generates moderation streams for" --> ContentListingAndStreaming + ModerationTools -- "applies to redditors" --> RedditorInteraction + ModerationTools -- "provides moderation capabilities for" --> SubredditManagement + SubredditWidgets -- "are managed by" --> SubredditManagement + ModmailConversations -- "are part of subreddit management" --> SubredditManagement + SubredditContentManagement -- "is managed by" --> SubredditManagement +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +This comprehensive component provides all tools necessary for managing user accounts, interacting with individual Redditor profiles, and moderating subreddits. It covers user preferences, inbox management, subreddit creation, moderation tools (modmail, notes, rules, removal reasons, wiki pages, widgets, emojis), and relationships within communities. + +### RedditClientCore +This component serves as the primary interface for interacting with the Reddit API, initializing core functionalities and providing access points to various Reddit resources. + + +**Related Classes/Methods**: + +- `praw.reddit.Reddit` (57:901) +- `praw.praw.models.front.Front` (17:32) +- `praw.praw.models.auth.Auth` (11:125) + + +### UserAccountManagement +This component handles functionalities related to the authenticated user's account, including managing inbox messages, user preferences, and retrieving information about the user's contributions and moderation roles. + + +**Related Classes/Methods**: + +- `praw.praw.models.inbox.Inbox` (18:324) +- `praw.praw.models.user.User` (24:259) +- `praw.models.preferences.Preferences` (14:204) + + +### RedditorInteraction +This component provides methods for interacting with individual Reddit users (Redditors), such as retrieving user profiles, managing friendships, and accessing user-specific content streams. + + +**Related Classes/Methods**: + +- `praw.praw.models.redditors.Redditors` (26:104) +- `praw.praw.models.reddit.redditor.Redditor` (21:409) +- `praw.praw.models.reddit.redditor.RedditorStream` (412:457) +- `praw.praw.models.reddit.user_subreddit.UserSubreddit` (14:78) + + +### SubredditManagement +This component manages core aspects of subreddits, including their creation and general properties. + + +**Related Classes/Methods**: + +- `praw.praw.models.subreddits.Subreddits` (19:133) +- `praw.praw.models.helpers.SubredditHelper` (301:353) +- `praw.praw.models.reddit.subreddit.Subreddit` (200:350) +- `praw.praw.models.reddit.subreddit.SubredditRelationship` (500:520) + + +### ModerationTools +This component encapsulates various tools and functionalities for subreddit moderators, including managing moderation notes, defining and enforcing rules, handling removal reasons, and managing moderation-related relationships. + + +**Related Classes/Methods**: + +- `praw.praw.models.reddit.user_subreddit.UserSubredditModeration` (82:199) +- `praw.praw.models.reddit.subreddit.ModeratorRelationship` (683:800) +- `praw.praw.models.reddit.subreddit.SubredditModeration` (500:700) +- `praw.praw.models.reddit.subreddit.SubredditModerationStream` (703:740) +- `praw.praw.models.mod_notes.BaseModNotes` (22:271) +- `praw.praw.models.mod_notes.RedditorModNotes` (274:367) +- `praw.praw.models.mod_notes.SubredditModNotes` (370:463) +- `praw.praw.models.mod_notes.RedditModNotes` (466:682) +- `praw.praw.models.reddit.rules.Rule` (19:100) +- `praw.praw.models.reddit.rules.SubredditRules` (189:314) +- `praw.praw.models.reddit.rules.RuleModeration` (103:186) +- `praw.praw.models.reddit.rules.SubredditRulesModeration` (317:413) +- `praw.praw.models.reddit.removal_reasons.RemovalReason` (18:114) +- `praw.praw.models.reddit.removal_reasons.SubredditRemovalReasons` (117:223) + + +### SubredditWidgets +This component manages the creation, modification, and display of various widgets on subreddit sidebars and other areas. + + +**Related Classes/Methods**: + +- `praw.praw.models.reddit.widgets.SubredditWidgets` (177:361) +- `praw.praw.models.reddit.widgets.Widget` (364:395) +- `praw.praw.models.reddit.widgets.CustomWidget` (639:710) +- `praw.praw.models.reddit.widgets.ModeratorsWidget` (894:933) +- `praw.praw.models.reddit.widgets.RulesWidget` (623:640) +- `praw.praw.models.reddit.widgets.SubredditWidgetsModeration` (283:390) +- `praw.praw.models.reddit.widgets.ButtonWidget` (410:497) +- `praw.praw.models.reddit.widgets.Calendar` (500:571) +- `praw.praw.models.reddit.widgets.CommunityList` (574:636) +- `praw.praw.models.reddit.widgets.IDCard` (713:748) +- `praw.praw.models.reddit.widgets.ImageWidget` (751:820) +- `praw.praw.models.reddit.widgets.Menu` (823:891) +- `praw.praw.models.reddit.widgets.PostFlairWidget` (936:1000) +- `praw.praw.models.reddit.widgets.TextArea` (1000:1090) + + +### ModmailConversations +This component handles the management of modmail conversations, allowing moderators to read, reply to, and manage messages within the modmail system. + + +**Related Classes/Methods**: + +- `praw.praw.models.reddit.modmail.ModmailConversation` (28:325) +- `praw.praw.models.reddit.modmail.ModmailAction` (328:329) +- `praw.praw.models.reddit.modmail.ModmailMessage` (332:333) +- `praw.praw.models.reddit.subreddit.Modmail` (20:100) + + +### SubredditContentManagement +This component manages content-related aspects within a subreddit, including flair, stylesheets, wiki pages, and emojis. + + +**Related Classes/Methods**: + +- `praw.praw.models.reddit.subreddit.SubredditFlair` (200:350) +- `praw.praw.models.reddit.subreddit.SubredditFlairTemplates` (353:490) +- `praw.praw.models.reddit.subreddit.SubredditStylesheet` (563:680) +- `praw.praw.models.reddit.subreddit.SubredditWiki` (743:780) +- `praw.praw.models.reddit.wikipage.WikiPage` (146:314) +- `praw.praw.models.reddit.wikipage.WikiPageModeration` (19:143) +- `praw.praw.models.reddit.emoji.Emoji` (16:131) +- `praw.praw.models.reddit.emoji.SubredditEmoji` (134:234) + + +### ContentListingAndStreaming +This component is responsible for generating iterable listings of Reddit content (like posts, comments, users, subreddits) and providing real-time streams of new content. + + +**Related Classes/Methods**: + +- `praw.models.listing.generator.ListingGenerator` (17:103) +- `praw.models.util.stream_generator` (36:163) +- `praw.praw.models.reddit.subreddit.SubredditStream` (523:560) +- `praw.praw.models.reddit.redditor.RedditorStream` (412:457) +- `praw.praw.models.reddit.subreddit.SubredditModerationStream` (703:740) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/on_boarding.md b/.codeboarding/on_boarding.md new file mode 100644 index 000000000..463ea0b3d --- /dev/null +++ b/.codeboarding/on_boarding.md @@ -0,0 +1,190 @@ +```mermaid +graph LR + PRAW_Core_API_Interaction["PRAW Core & API Interaction"] + Reddit_Data_Models["Reddit Data Models"] + Content_Listing_Management["Content & Listing Management"] + User_Community_Management["User & Community Management"] + Specialized_Content_Features["Specialized Content Features"] + Development_Build_Tools["Development & Build Tools"] + PRAW_Core_API_Interaction -- "communicates with" --> Reddit_Data_Models + PRAW_Core_API_Interaction -- "processes requests for" --> Content_Listing_Management + PRAW_Core_API_Interaction -- "processes requests for" --> User_Community_Management + PRAW_Core_API_Interaction -- "processes requests for" --> Specialized_Content_Features + Reddit_Data_Models -- "defines structure for" --> Content_Listing_Management + Reddit_Data_Models -- "defines structure for" --> User_Community_Management + Reddit_Data_Models -- "defines structure for" --> Specialized_Content_Features + Content_Listing_Management -- "utilizes" --> PRAW_Core_API_Interaction + Content_Listing_Management -- "generates" --> Reddit_Data_Models + User_Community_Management -- "utilizes" --> PRAW_Core_API_Interaction + User_Community_Management -- "operates on" --> Reddit_Data_Models + Specialized_Content_Features -- "utilizes" --> PRAW_Core_API_Interaction + Specialized_Content_Features -- "operates on" --> Reddit_Data_Models + Development_Build_Tools -- "analyzes" --> PRAW_Core_API_Interaction + Development_Build_Tools -- "tests" --> Reddit_Data_Models + click PRAW_Core_API_Interaction href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/praw/PRAW Core & API Interaction.md" "Details" + click Reddit_Data_Models href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/praw/Reddit Data Models.md" "Details" + click Content_Listing_Management href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/praw/Content & Listing Management.md" "Details" + click User_Community_Management href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/praw/User & Community Management.md" "Details" + click Specialized_Content_Features href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/praw/Specialized Content Features.md" "Details" + click Development_Build_Tools href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/praw/Development & Build Tools.md" "Details" +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +The PRAW library provides a Pythonic interface to the Reddit API, enabling developers to interact with Reddit programmatically. The main flow involves a core API interaction component that handles requests and responses, utilizing data models to represent Reddit entities. Various management components then leverage this core and data models to handle specific functionalities like content listing, user interactions, community moderation, and specialized content features. Development tools support the library's maintenance and release processes. + +### PRAW Core & API Interaction +The foundational layer of the PRAW library, managing core interaction with the Reddit API. It handles client configuration, request objectification, and the processing of API responses, including error handling. It ensures all communications with Reddit are properly authenticated and formatted. + + +**Related Classes/Methods**: + +- `praw.praw.reddit.Reddit` (57:901) +- `praw.praw.objector.Objector` (17:263) +- `praw.praw.exceptions.MediaPostFailed` (158:167) +- `praw.praw.exceptions.RedditAPIException` (170:201) +- `praw.praw.config.Config` (27:173) +- `praw.praw.util.snake` (6:19) + + +### Reddit Data Models +Provides the fundamental base classes and mixins that define the structure and common behaviors of various Reddit entities (like submissions, comments, users, and subreddits). It serves as the blueprint for how PRAW represents data received from the Reddit API, enabling consistent attribute access and basic functionalities across different object types. + + +**Related Classes/Methods**: + +- `praw.praw.models.base.PRAWBase` (12:47) +- `praw.praw.models.reddit.base.RedditBase` (16:90) +- `praw.praw.models.reddit.mixins.votable.VotableMixin` (8:92) +- `praw.praw.models.reddit.mixins.ThingModerationMixin` (10:120) +- `praw.praw.models.list.base.BaseList` (15:54) + + +### Content & Listing Management +Responsible for efficiently retrieving and iterating through various types of content listings from Reddit, such as hot, new, or top posts. It also provides utilities for real-time data streams and handles the creation, retrieval, and general management of Reddit submissions (posts) and comments, including drafts and poll data. + + +**Related Classes/Methods**: + +- `praw.praw.models.listing.generator.ListingGenerator` (17:103) +- `praw.praw.models.listing.domain.DomainListing` (14:25) +- `praw.praw.models.listing.mixins.redditor.SubListing` (18:32) +- `praw.praw.models.listing.mixins.redditor.RedditorListingMixin` (35:185) +- `praw.praw.models.listing.mixins.subreddit.CommentHelper` (20:46) +- `praw.praw.models.listing.mixins.subreddit.SubredditListingMixin` (49:73) +- `praw.praw.models.listing.mixins.rising.RisingListingMixin` (17:34) +- `praw.praw.models.listing.mixins.base.BaseListingMixin` (15:149) +- `praw.praw.models.listing.mixins.submission.SubmissionListingMixin` (17:42) +- `praw.praw.models.util` (10:190) +- `praw.praw.models.comment_forest.CommentForest` (15:202) +- `praw.praw.models.reddit.comment.Comment` (19:311) +- `praw.praw.models.reddit.comment.CommentModeration` (314:350) +- `praw.praw.models.reddit.more.MoreComments` (14:87) +- `praw.praw.models.reddit.submission.Submission` (395:916) +- `praw.praw.models.reddit.submission.SubmissionFlair` (40:90) +- `praw.praw.models.reddit.submission.SubmissionModeration` (93:392) +- `praw.praw.models.helpers.DraftHelper` (20:133) +- `praw.praw.models.reddit.draft.Draft` (17:292) +- `praw.praw.models.reddit.poll.PollData` (47:112) +- `praw.praw.models.reddit.poll.PollOption` (11:44) + + +### User & Community Management +This comprehensive component provides all tools necessary for managing user accounts, interacting with individual Redditor profiles, and moderating subreddits. It covers user preferences, inbox management, subreddit creation, moderation tools (modmail, notes, rules, removal reasons, wiki pages, widgets, emojis), and relationships within communities. + + +**Related Classes/Methods**: + +- `praw.praw.models.front.Front` (17:32) +- `praw.praw.models.inbox.Inbox` (18:324) +- `praw.praw.models.auth.Auth` (11:125) +- `praw.praw.models.user.User` (24:259) +- `praw.praw.models.redditors.Redditors` (26:104) +- `praw.praw.models.reddit.redditor.Redditor` (21:409) +- `praw.praw.models.reddit.redditor.RedditorStream` (412:457) +- `praw.praw.models.reddit.user_subreddit.UserSubreddit` (14:78) +- `praw.praw.models.reddit.user_subreddit.UserSubredditModeration` (82:199) +- `praw.praw.models.subreddits.Subreddits` (19:133) +- `praw.praw.models.helpers.SubredditHelper` (301:353) +- `praw.praw.models.reddit.subreddit.Subreddit` (200:350) +- `praw.praw.models.reddit.subreddit.SubredditRelationship` (500:520) +- `praw.praw.models.reddit.subreddit.SubredditStream` (523:560) +- `praw.praw.models.reddit.subreddit.SubredditStylesheet` (563:680) +- `praw.praw.models.reddit.subreddit.ModeratorRelationship` (683:800) +- `praw.praw.models.reddit.subreddit.Modmail` (20:100) +- `praw.praw.models.reddit.subreddit.SubredditFlair` (200:350) +- `praw.praw.models.reddit.subreddit.SubredditFlairTemplates` (353:490) +- `praw.praw.models.reddit.subreddit.SubredditModeration` (500:700) +- `praw.praw.models.reddit.subreddit.SubredditModerationStream` (703:740) +- `praw.praw.models.reddit.subreddit.SubredditWiki` (743:780) +- `praw.praw.models.mod_notes.BaseModNotes` (22:271) +- `praw.praw.models.mod_notes.RedditorModNotes` (274:367) +- `praw.praw.models.mod_notes.SubredditModNotes` (370:463) +- `praw.praw.models.mod_notes.RedditModNotes` (466:682) +- `praw.praw.models.reddit.modmail.ModmailConversation` (28:325) +- `praw.praw.models.reddit.modmail.ModmailAction` (328:329) +- `praw.praw.models.reddit.modmail.ModmailMessage` (332:333) +- `praw.praw.models.reddit.rules.Rule` (19:100) +- `praw.praw.models.reddit.rules.SubredditRules` (189:314) +- `praw.praw.models.reddit.rules.RuleModeration` (103:186) +- `praw.praw.models.reddit.rules.SubredditRulesModeration` (317:413) +- `praw.praw.models.reddit.removal_reasons.RemovalReason` (18:114) +- `praw.praw.models.reddit.removal_reasons.SubredditRemovalReasons` (117:223) +- `praw.praw.models.reddit.wikipage.WikiPage` (146:314) +- `praw.praw.models.reddit.wikipage.WikiPageModeration` (19:143) +- `praw.praw.models.reddit.emoji.Emoji` (16:131) +- `praw.praw.models.reddit.emoji.SubredditEmoji` (134:234) +- `praw.praw.models.reddit.widgets.SubredditWidgets` (177:361) +- `praw.praw.models.reddit.widgets.Widget` (364:395) +- `praw.praw.models.reddit.widgets.CustomWidget` (639:710) +- `praw.praw.models.reddit.widgets.ModeratorsWidget` (894:933) +- `praw.praw.models.reddit.widgets.RulesWidget` (623:640) +- `praw.praw.models.reddit.widgets.SubredditWidgetsModeration` (283:390) +- `praw.praw.models.reddit.widgets.ButtonWidget` (410:497) +- `praw.praw.models.reddit.widgets.Calendar` (500:571) +- `praw.praw.models.reddit.widgets.CommunityList` (574:636) +- `praw.praw.models.reddit.widgets.IDCard` (713:748) +- `praw.praw.models.reddit.widgets.ImageWidget` (751:820) +- `praw.praw.models.reddit.widgets.Menu` (823:891) +- `praw.praw.models.reddit.widgets.PostFlairWidget` (936:1000) +- `praw.praw.models.reddit.widgets.TextArea` (1000:1090) + + +### Specialized Content Features +Manages specialized content types on Reddit, including Live Threads, Multireddits, and Collections. It provides dedicated interfaces for interacting with these unique content structures and their specific functionalities. + + +**Related Classes/Methods**: + +- `praw.praw.models.helpers.LiveHelper` (136:238) +- `praw.praw.models.reddit.live.LiveContributorRelationship` (22:258) +- `praw.praw.models.reddit.live.LiveThread` (261:471) +- `praw.praw.models.reddit.live.LiveThreadContribution` (474:582) +- `praw.praw.models.reddit.live.LiveThreadStream` (585:637) +- `praw.praw.models.reddit.live.LiveUpdate` (700:792) +- `praw.praw.models.reddit.live.LiveUpdateContribution` (640:697) +- `praw.praw.models.helpers.MultiredditHelper` (241:298) +- `praw.praw.models.reddit.multi.Multireddit` (20:228) +- `praw.praw.models.reddit.collections.CollectionModeration` (21:216) +- `praw.praw.models.reddit.collections.SubredditCollectionsModeration` (219:288) +- `praw.praw.models.reddit.collections.SubredditCollections` (291:377) +- `praw.praw.models.reddit.collections.Collection` (380:575) + + +### Development & Build Tools +This component comprises scripts and utilities primarily used for the development, testing, and release management of the PRAW library itself. It includes tools for static analysis, unit testing, and version control, and is not part of the library's runtime functionality. + + +**Related Classes/Methods**: + +- `praw.pre_push` (2:80) +- `praw.tools.static_word_checks` (5:100) +- `praw.tools.check_documentation` (5:70) +- `praw.tools.set_active_docs` (5:80) +- `praw.tools.set_version` (5:100) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file From 3a196f664e56a80c3aeadc6fe359584ac6af7497 Mon Sep 17 00:00:00 2001 From: ivanmilevtues Date: Mon, 1 Sep 2025 19:04:37 +0200 Subject: [PATCH 02/23] Added github action --- .github/workflows/docs_codeboarding.yml | 122 ++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 .github/workflows/docs_codeboarding.yml diff --git a/.github/workflows/docs_codeboarding.yml b/.github/workflows/docs_codeboarding.yml new file mode 100644 index 000000000..11262b34a --- /dev/null +++ b/.github/workflows/docs_codeboarding.yml @@ -0,0 +1,122 @@ +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: '.md' + type: choice + options: + - '.md' + - '.mdx' + - '.rst' + 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 || '.md' }} + + - 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 }}" + + # 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 || '.md' }} + - 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 From f2a2e7884e4c4cd77887970471d090bd0da12349 Mon Sep 17 00:00:00 2001 From: ivanmilevtues Date: Mon, 1 Sep 2025 19:04:56 +0200 Subject: [PATCH 03/23] Added codeboarding --- .codeboarding/Content & Listing Management.md | 170 --------------- .codeboarding/Development & Build Tools.md | 88 -------- .codeboarding/PRAW Core & API Interaction.md | 133 ------------ .codeboarding/Reddit Data Models.md | 172 --------------- .codeboarding/Specialized Content Features.md | 204 ------------------ .codeboarding/User & Community Management.md | 172 --------------- .codeboarding/on_boarding.md | 190 ---------------- 7 files changed, 1129 deletions(-) delete mode 100644 .codeboarding/Content & Listing Management.md delete mode 100644 .codeboarding/Development & Build Tools.md delete mode 100644 .codeboarding/PRAW Core & API Interaction.md delete mode 100644 .codeboarding/Reddit Data Models.md delete mode 100644 .codeboarding/Specialized Content Features.md delete mode 100644 .codeboarding/User & Community Management.md delete mode 100644 .codeboarding/on_boarding.md diff --git a/.codeboarding/Content & Listing Management.md b/.codeboarding/Content & Listing Management.md deleted file mode 100644 index df59a1bc1..000000000 --- a/.codeboarding/Content & Listing Management.md +++ /dev/null @@ -1,170 +0,0 @@ -```mermaid -graph LR - Reddit_Client["Reddit Client"] - Content_Listing_Management["Content & Listing Management"] - Listing_Generators["Listing Generators"] - Comment_Objects["Comment Objects"] - Submission_Objects["Submission Objects"] - Subreddit_Objects["Subreddit Objects"] - User_Objects["User Objects"] - Inbox_Manager["Inbox Manager"] - Draft_Management["Draft Management"] - Stream_Utilities["Stream Utilities"] - Listing_Mixins["Listing Mixins"] - Reddit_Client -- "Provides access to" --> Comment_Objects - Reddit_Client -- "Provides access to" --> Submission_Objects - Reddit_Client -- "Provides access to" --> Subreddit_Objects - Reddit_Client -- "Provides access to" --> User_Objects - Reddit_Client -- "Manages user inbox through" --> Inbox_Manager - Reddit_Client -- "Manages drafts through" --> Draft_Management - Reddit_Client -- "Provides access to" --> Content_Listing_Management - Content_Listing_Management -- "Uses" --> Listing_Generators - Content_Listing_Management -- "Manages" --> Comment_Objects - Content_Listing_Management -- "Manages" --> Submission_Objects - Content_Listing_Management -- "Uses" --> Listing_Mixins - Content_Listing_Management -- "Uses" --> Draft_Management - Content_Listing_Management -- "Uses" --> Stream_Utilities - Inbox_Manager -- "Uses for data retrieval" --> Listing_Generators - Listing_Mixins -- "Implements listings via" --> Listing_Generators - Stream_Utilities -- "Can consume output from" --> Listing_Generators - Comment_Objects -- "Forms hierarchical structures with" --> Comment_Objects - Submission_Objects -- "Contains comments" --> Comment_Objects - Subreddit_Objects -- "Receives submissions" --> Submission_Objects - Subreddit_Objects -- "Extends with listing features" --> Listing_Mixins - User_Objects -- "Enables streaming of user content" --> Stream_Utilities - Subreddit_Objects -- "Enables streaming of subreddit content" --> Stream_Utilities - Listing_Generators -- "Produces" --> Comment_Objects - Listing_Generators -- "Produces" --> Submission_Objects - Listing_Generators -- "Produces" --> User_Objects - Listing_Generators -- "Produces" --> Subreddit_Objects -``` -[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) - -## Component Details - -This graph illustrates the architecture of the Content & Listing Management subsystem within the PRAW library, focusing on how it retrieves, iterates, and manages various types of Reddit content. The core functionality revolves around efficient listing generation and the handling of submissions, comments, and related data like drafts and polls. It interacts with the central Reddit Client for API access and leverages specialized components for listing generation, stream utilities, and specific Reddit object management. - -### Reddit Client -The central entry point for interacting with the Reddit API, managing authentication and providing access to various Reddit entities. - - -**Related Classes/Methods**: - -- `praw.praw.reddit.Reddit` (57:901) - - -### Content & Listing Management -Responsible for efficiently retrieving and iterating through various types of content listings from Reddit, such as hot, new, or top posts. It also provides utilities for real-time data streams and handles the creation, retrieval, and general management of Reddit submissions (posts) and comments, including drafts and poll data. - - -**Related Classes/Methods**: - -- `praw.praw.models.listing.generator.ListingGenerator` (17:103) -- `praw.praw.models.listing.domain.DomainListing` (14:25) -- `praw.praw.models.listing.mixins.redditor.SubListing` (18:32) -- `praw.praw.models.listing.mixins.redditor.RedditorListingMixin` (35:185) -- `praw.praw.models.listing.mixins.subreddit.CommentHelper` (20:46) -- `praw.praw.models.listing.mixins.subreddit.SubredditListingMixin` (49:73) -- `praw.praw.models.listing.mixins.rising.RisingListingMixin` (17:34) -- `praw.praw.models.listing.mixins.base.BaseListingMixin` (15:149) -- `praw.praw.models.listing.mixins.submission.SubmissionListingMixin` (17:42) -- `praw.praw.models.util` (10:190) -- `praw.praw.models.comment_forest.CommentForest` (15:202) -- `praw.praw.models.reddit.comment.Comment` (19:311) -- `praw.praw.models.reddit.comment.CommentModeration` (314:350) -- `praw.praw.models.reddit.more.MoreComments` (14:87) -- `praw.praw.models.reddit.submission.Submission` (395:916) -- `praw.praw.models.reddit.submission.SubmissionFlair` (40:90) -- `praw.praw.models.reddit.submission.SubmissionModeration` (93:392) -- `praw.praw.models.helpers.DraftHelper` (20:133) -- `praw.praw.models.reddit.draft.Draft` (17:292) -- `praw.praw.models.reddit.poll.PollData` (47:112) -- `praw.praw.models.reddit.poll.PollOption` (11:44) - - -### Listing Generators -A core component responsible for iterating and fetching paginated lists of various Reddit objects. - - -**Related Classes/Methods**: - -- `praw.models.listing.generator.ListingGenerator` (17:103) - - -### Comment Objects -Represents individual Reddit comments, providing methods for interaction and retrieval of related data. - - -**Related Classes/Methods**: - -- `praw.praw.models.reddit.comment.Comment` (19:311) - - -### Submission Objects -Represents Reddit posts (submissions), offering functionalities for content manipulation and moderation. - - -**Related Classes/Methods**: - -- `praw.praw.models.reddit.submission.Submission` (395:916) - - -### Subreddit Objects -Represents Reddit communities (subreddits), enabling content submission and moderation within them. - - -**Related Classes/Methods**: - -- `praw.praw.models.reddit.subreddit.Subreddit` (full file reference) - - -### User Objects -Represents Reddit user accounts, providing access to user-specific content and profiles. - - -**Related Classes/Methods**: - -- `praw.praw.models.reddit.redditor.Redditor` (21:409) - - -### Inbox Manager -Manages the authenticated user's Reddit inbox, allowing retrieval of messages, comment replies, and mentions. - - -**Related Classes/Methods**: - -- `praw.praw.models.inbox.Inbox` (18:324) - - -### Draft Management -Provides utilities for creating and managing submission drafts. - - -**Related Classes/Methods**: - -- `praw.praw.models.helpers.DraftHelper` (20:133) - - -### Stream Utilities -Offers helper functions for continuously streaming new Reddit content, such as comments or submissions. - - -**Related Classes/Methods**: - -- `praw.praw.models.util.stream_generator` (36:163) - - -### Listing Mixins -Abstract classes providing common methods for fetching various types of listings (e.g., hot, new, top) across different Reddit entities. - - -**Related Classes/Methods**: - -- `praw.praw.models.listing.mixins.base.BaseListingMixin` (15:149) -- `praw.praw.models.listing.mixins.redditor.RedditorListingMixin` (35:185) -- `praw.praw.models.listing.mixins.subreddit.SubredditListingMixin` (49:73) - - - - -### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Development & Build Tools.md b/.codeboarding/Development & Build Tools.md deleted file mode 100644 index 12e4a3c53..000000000 --- a/.codeboarding/Development & Build Tools.md +++ /dev/null @@ -1,88 +0,0 @@ -```mermaid -graph LR - Pre_Push_Automation["Pre-Push Automation"] - Static_Word_Checks["Static Word Checks"] - Documentation_Checks["Documentation Checks"] - Active_Documentation_Management["Active Documentation Management"] - Version_Management["Version Management"] - Pre_Push_Automation -- "orchestrates" --> Static_Word_Checks - Pre_Push_Automation -- "orchestrates" --> Documentation_Checks - Pre_Push_Automation -- "utilizes" --> Version_Management -``` -[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) - -## Component Details - -This component comprises scripts and utilities primarily used for the development, testing, and release management of the PRAW library itself. It includes tools for static analysis, unit testing, and version control, and is not part of the library's runtime functionality. - -### Pre-Push Automation -This component automates pre-push checks, including running static analysis (pre-commit, sphinx-build) and unit tests (pytest). It orchestrates the execution of these checks and reports their success or failure. - - -**Related Classes/Methods**: - -- `praw.pre_push` (2:80) -- `praw.pre_push.main` (58:98) -- `praw.pre_push.run_static` (32:45) -- `praw.pre_push.run_unit` (48:55) -- `praw.pre_push.do_process` (10:29) - - -### Static Word Checks -This component is responsible for performing static analysis on the codebase, specifically checking for double syntax and 'noreturn' patterns within the code. It uses a dedicated checker class to encapsulate this logic. - - -**Related Classes/Methods**: - -- `praw.tools.static_word_checks` (5:100) -- `praw.tools.static_word_checks.main` (120:140) -- `praw.tools.static_word_checks.StaticChecker` (8:117) -- `praw.tools.static_word_checks.StaticChecker.run_checks` (75:117) -- `praw.tools.static_word_checks.StaticChecker.check_for_double_syntax` (27:55) -- `praw.tools.static_word_checks.StaticChecker.check_for_noreturn` (57:73) - - -### Documentation Checks -This component focuses on verifying the documentation, particularly by discovering and checking subclasses for proper documentation. It ensures consistency and completeness of the project's documentation. - - -**Related Classes/Methods**: - -- `praw.tools.check_documentation` (5:70) -- `praw.tools.check_documentation.main` (80:81) -- `praw.tools.check_documentation.DocumentationChecker` (16:77) -- `praw.tools.check_documentation.DocumentationChecker.check` (46:77) -- `praw.tools.check_documentation.DocumentationChecker.discover_subclasses` (36:43) - - -### Active Documentation Management -This component manages the active documentation versions, primarily by fetching available versions. It likely supports processes related to deploying or updating documentation. - - -**Related Classes/Methods**: - -- `praw.tools.set_active_docs` (5:80) -- `praw.tools.set_active_docs.main` (32:90) -- `praw.tools.set_active_docs.fetch_versions` (14:29) - - -### Version Management -This component handles the project's versioning, including managing unreleased changes, updating the changelog, incrementing development versions, and updating package version information. It ensures proper version control and release preparation. - - -**Related Classes/Methods**: - -- `praw.tools.set_version` (5:100) -- `praw.tools.set_version.main` (64:70) -- `praw.tools.set_version.handle_unreleased` (32:33) -- `praw.tools.set_version.handle_version` (36:40) -- `praw.tools.set_version.add_unreleased_to_changelog` (15:29) -- `praw.tools.set_version.increment_development_version` (43:61) -- `praw.tools.set_version.valid_version` (107:112) -- `praw.tools.set_version.update_changelog` (73:88) -- `praw.tools.set_version.update_package` (91:104) - - - - -### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/PRAW Core & API Interaction.md b/.codeboarding/PRAW Core & API Interaction.md deleted file mode 100644 index 76bef443a..000000000 --- a/.codeboarding/PRAW Core & API Interaction.md +++ /dev/null @@ -1,133 +0,0 @@ -```mermaid -graph LR - RedditClientCore["RedditClientCore"] - ObjectTransformationLayer["ObjectTransformationLayer"] - ConfigurationManagement["ConfigurationManagement"] - ExceptionHandling["ExceptionHandling"] - UtilityFunctions["UtilityFunctions"] - RedditClientCore -- "loads configuration from" --> ConfigurationManagement - RedditClientCore -- "accesses settings from" --> ConfigurationManagement - RedditClientCore -- "uses for objectification" --> ObjectTransformationLayer - RedditClientCore -- "initializes" --> ObjectTransformationLayer - RedditClientCore -- "raises" --> ExceptionHandling - RedditClientCore -- "handles" --> ExceptionHandling - ObjectTransformationLayer -- "raises" --> ExceptionHandling - ObjectTransformationLayer -- "parses errors using" --> ExceptionHandling - ObjectTransformationLayer -- "uses for key conversion" --> UtilityFunctions - ConfigurationManagement -- "raises" --> ExceptionHandling -``` -[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) - -## Component Details - -This graph represents the core interaction layer of the PRAW library with the Reddit API. The main flow involves the `RedditClientCore` initiating API requests, which are then processed by the `ObjectTransformationLayer` to convert raw responses into structured Python objects. `ConfigurationManagement` provides necessary settings for the client, while `ExceptionHandling` ensures robust error management across these interactions. `UtilityFunctions` support various operations, including data transformation for consistency. - -### RedditClientCore -This component serves as the central interface for interacting with the Reddit API. It manages the lifecycle of API interactions, including initialization, authentication, and dispatching various types of HTTP requests (GET, POST, PUT, DELETE, PATCH). It also integrates with other components to handle objectification of responses, rate limiting, and update checks, providing a comprehensive entry point for PRAW users. - - -**Related Classes/Methods**: - -- `praw.praw.reddit.Reddit` (57:901) -- `praw.praw.reddit.Reddit:read_only` (87:89) -- `praw.praw.reddit.Reddit:__init__` (114:386) -- `praw.praw.reddit.Reddit:_objectify_request` (435:469) -- `praw.praw.reddit.Reddit:_prepare_objector` (479:525) -- `praw.praw.reddit.Reddit:_prepare_prawcore` (527:546) -- `praw.praw.reddit.Reddit:_prepare_trusted_prawcore` (548:564) -- `praw.praw.reddit.Reddit:_prepare_untrusted_prawcore` (566:570) -- `praw.praw.reddit.Reddit:_resolve_share_url` (572:580) -- `praw.praw.reddit.Reddit:comment` (582:596) -- `praw.praw.reddit.Reddit:delete` (598:617) -- `praw.praw.reddit.Reddit:domain` (619:625) -- `praw.praw.reddit.Reddit:get` (627:639) -- `praw.praw.reddit.Reddit:info` (641:720) -- `praw.praw.reddit.Reddit:patch` (722:741) -- `praw.praw.reddit.Reddit:post` (743:789) -- `praw.praw.reddit.Reddit:put` (791:808) -- `praw.praw.reddit.Reddit:redditor` (810:819) -- `praw.praw.reddit.Reddit:request` (821:876) -- `praw.praw.reddit.Reddit:submission` (878:889) -- `praw.praw.reddit.Reddit:username_available` (891:901) -- `praw.praw.reddit.Reddit._check_for_update` (413:418) -- `praw.praw.reddit.Reddit._check_for_async` (388:411) -- `praw.praw.reddit.Reddit._handle_rate_limit` (420:433) -- `praw.praw.reddit.Reddit._prepare_common_authorizer` (471:477) -- `praw.models.auth.Auth` (11:125) -- `praw.models.helpers.DraftHelper` (20:133) -- `praw.models.front.Front` (17:32) -- `praw.models.inbox.Inbox` (18:324) -- `praw.models.helpers.LiveHelper` (136:238) -- `praw.models.helpers.MultiredditHelper` (241:298) -- `praw.models.mod_notes.RedditModNotes` (466:682) -- `praw.models.redditors.Redditors` (26:104) -- `praw.models.helpers.SubredditHelper` (301:353) -- `praw.models.subreddits.Subreddits` (19:133) -- `praw.models.user.User` (24:259) -- `praw.models.reddit.comment.Comment` (19:311) -- `praw.models.listing.domain.DomainListing` (14:25) -- `praw.models.reddit.redditor.Redditor` (21:409) -- `praw.models.reddit.submission.Submission` (395:916) - - -### ObjectTransformationLayer -This component is responsible for transforming raw JSON responses received from the Reddit API into structured Python objects that PRAW users can easily interact with. It also includes functionality for parsing and handling API-specific errors embedded within the responses and converting dictionary keys from camelCase to snake_case for Pythonic consistency. - - -**Related Classes/Methods**: - -- `praw.praw.objector.Objector` (17:263) -- `praw.praw.objector.Objector:check_error` (21:24) -- `praw.praw.objector.Objector:parse_error` (27:48) -- `praw.praw.objector.Objector:_objectify_dict` (59:201) -- `praw.praw.objector.Objector:objectify` (203:263) - - -### ConfigurationManagement -This component is dedicated to loading, managing, and providing access to PRAW's configuration settings. It supports reading configurations from various sources, such as a 'praw.ini' file or environment variables, ensuring that the Reddit client is properly configured with necessary credentials and API parameters. - - -**Related Classes/Methods**: - -- `praw.praw.config.Config` (27:173) -- `praw.praw.config.Config:short_url` (74:83) -- `praw.praw.config.Config:__init__` (85:103) -- `praw.praw.config.Config:_fetch_default` (110:113) -- `praw.praw.config.Config:_fetch_or_not_set` (115:123) -- `praw.praw.config.Config:_initialize_attributes` (125:173) -- `praw.praw.config.Config:_load_config` (45:71) -- `praw.praw.config.Config:_config_boolean` (39:42) -- `praw.praw.config.Config:_fetch` (105:108) - - -### ExceptionHandling -This component centralizes the definition and management of custom exceptions within PRAW. It provides a structured way to handle various error conditions, including client-side issues, Reddit API errors, and specific operational failures like media post failures or missing attributes, ensuring robust error reporting and recovery. - - -**Related Classes/Methods**: - -- `praw.praw.exceptions.MediaPostFailed` (158:167) -- `praw.praw.exceptions.RedditAPIException` (170:201) -- `praw.praw.exceptions.ClientException` (74:75) -- `praw.praw.exceptions.MissingRequiredAttributeException` (121:122) -- `praw.praw.exceptions.RedditAPIException:parse_exception_list` (174:189) -- `praw.praw.exceptions.RedditAPIException:__init__` (191:201) -- `praw.praw.exceptions.RedditErrorItem` (18:71) -- `praw.praw.exceptions.MediaPostFailed:__init__` (161:167) -- `praw.praw.exceptions.WebSocketException.__init__` (149:155) - - -### UtilityFunctions -This component provides a collection of general-purpose utility functions that support various operations within PRAW. Specifically, it includes functions for string manipulation, such as converting dictionary keys from camelCase to snake_case, which is crucial for maintaining consistent naming conventions across the library's object model. - - -**Related Classes/Methods**: - -- `praw.praw.util.snake` (6:19) -- `praw.praw.util.snake:snake_case_keys` (16:22) -- `praw.praw.util.snake:camel_to_snake` (11:13) - - - - -### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Reddit Data Models.md b/.codeboarding/Reddit Data Models.md deleted file mode 100644 index 98b4f9d92..000000000 --- a/.codeboarding/Reddit Data Models.md +++ /dev/null @@ -1,172 +0,0 @@ -```mermaid -graph LR - PRAWBase_Component["PRAWBase Component"] - RedditBase_Component["RedditBase Component"] - Listing_Generation_Component["Listing Generation Component"] - Listing_Mixins_Component["Listing Mixins Component"] - Subreddit_Management_Component["Subreddit Management Component"] - Comment_Management_Component["Comment Management Component"] - Submission_Management_Component["Submission Management Component"] - Voting_Mechanism_Component["Voting Mechanism Component"] - Moderation_Mixin_Component["Moderation Mixin Component"] - Base_List_Component["Base List Component"] - RedditBase_Component -- "inherits from" --> PRAWBase_Component - Listing_Generation_Component -- "inherits from" --> PRAWBase_Component - Base_List_Component -- "inherits from" --> PRAWBase_Component - Subreddit_Management_Component -- "inherits from" --> RedditBase_Component - Comment_Management_Component -- "inherits from" --> RedditBase_Component - Submission_Management_Component -- "inherits from" --> RedditBase_Component - Listing_Mixins_Component -- "utilizes" --> Listing_Generation_Component - Listing_Mixins_Component -- "depends on" --> PRAWBase_Component - Subreddit_Management_Component -- "utilizes" --> Listing_Generation_Component - Voting_Mechanism_Component -- "applies to" --> RedditBase_Component - Moderation_Mixin_Component -- "applies to" --> RedditBase_Component - Moderation_Mixin_Component -- "provides moderation to" --> Comment_Management_Component - Moderation_Mixin_Component -- "provides moderation to" --> Submission_Management_Component -``` -[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) - -## Component Details - -This graph provides an overview of the Reddit Data Models subsystem in PRAW, which defines the foundational structure and common behaviors for various Reddit entities. It illustrates how core base classes like PRAWBase and RedditBase establish the blueprint for data representation, while specialized components manage specific Reddit objects such as subreddits, comments, and submissions. Mixin components integrate common functionalities like voting, moderation, and listing generation across different data models, ensuring consistent interaction with the Reddit API and efficient data handling. - -### PRAWBase Component -This component serves as the foundational superclass for all models within the PRAW library. It provides core utilities such as safely adding arguments to dictionaries and a class method for parsing data into PRAWBase instances. It initializes instances with a Reddit object and optional initial data. - - -**Related Classes/Methods**: - -- `praw.models.base.PRAWBase` (12:47) -- `praw.models.base.PRAWBase._safely_add_arguments` (16:26) -- `praw.models.base.PRAWBase.parse` (29:36) -- `praw.models.base.PRAWBase.__init__` (38:47) - - -### RedditBase Component -Building upon PRAWBase, this component represents actual Reddit objects. It includes functionalities for parsing URLs, handling attribute access (fetching data if not already fetched), and defining equality/hashing for Reddit objects. It also provides methods for fetching data from the Reddit API and resetting attributes. - - -**Related Classes/Methods**: - -- `praw.models.reddit.base.RedditBase` (16:90) -- `praw.models.reddit.base.RedditBase._url_parts` (20:24) -- `praw.models.reddit.base.RedditBase.__getattr__` (32:38) -- `praw.models.reddit.base.RedditBase.__init__` (44:64) -- `praw.models.reddit.base.RedditBase._fetch` (78:79) -- `praw.models.reddit.base.RedditBase._fetch_data` (81:84) -- `praw.models.reddit.base.RedditBase._reset_attributes` (86:90) - - -### Listing Generation Component -This component is responsible for generating and iterating through various Reddit listings, such as comments, submissions, or other content. It manages the fetching of batches of items from the Reddit API and handles pagination to provide a continuous stream of content. - - -**Related Classes/Methods**: - -- `praw.models.listing.generator.ListingGenerator` (17:103) -- `praw.models.listing.generator.ListingGenerator.__init__` (29:56) -- `praw.models.listing.generator.ListingGenerator.__iter__` (58:60) -- `praw.models.listing.generator.ListingGenerator.__next__` (62:73) -- `praw.models.listing.generator.ListingGenerator._extract_sublist` (75:87) -- `praw.models.listing.generator.ListingGenerator._next_batch` (89:103) - - -### Listing Mixins Component -This component provides a set of mixin classes that add common listing functionalities to various Reddit objects. It includes methods for retrieving controversial, hot, new, and top items, with support for time filters and argument preparation for API requests. - - -**Related Classes/Methods**: - -- `praw.models.listing.mixins.base.BaseListingMixin` (15:149) -- `praw.models.listing.mixins.base.BaseListingMixin._validate_time_filter` (21:30) -- `praw.models.listing.mixins.base.BaseListingMixin._prepare` (32:37) -- `praw.models.listing.mixins.base.BaseListingMixin.controversial` (39:72) -- `praw.models.listing.mixins.base.BaseListingMixin.hot` (74:94) -- `praw.models.listing.mixins.base.BaseListingMixin.new` (96:116) -- `praw.models.listing.mixins.base.BaseListingMixin.top` (118:149) - - -### Subreddit Management Component -This component encapsulates functionalities related to managing subreddits, including retrieving subreddit information, moderating content, and handling subreddit-specific streams like comments and submissions. It also provides methods for managing subreddit relationships and stylesheets. - - -**Related Classes/Methods**: - -- `praw.models.reddit.subreddit.Subreddit` (full file reference) -- `praw.models.reddit.subreddit.Subreddit.__init__` (full file reference) -- `praw.models.reddit.subreddit.Subreddit._fetch` (full file reference) -- `praw.models.reddit.subreddit.Subreddit.search` (full file reference) -- `praw.models.reddit.subreddit.SubredditModeration.log` (full file reference) -- `praw.models.reddit.subreddit.SubredditModeration.unmoderated` (full file reference) -- `praw.models.reddit.subreddit.SubredditStream.comments` (full file reference) -- `praw.models.reddit.subreddit.SubredditStream.submissions` (full file reference) - - -### Comment Management Component -This component handles operations related to Reddit comments. It provides methods for initializing comment instances, extracting comment IDs from URLs, accessing comment replies, and refreshing comment attributes. It also includes moderation functionalities specific to comments. - - -**Related Classes/Methods**: - -- `praw.models.reddit.comment.Comment` (19:311) -- `praw.models.reddit.comment.Comment.id_from_url` (64:74) -- `praw.models.reddit.comment.Comment.__init__` (143:163) -- `praw.models.reddit.comment.Comment._fetch` (185:196) -- `praw.models.reddit.comment.Comment.parent` (201:262) -- `praw.models.reddit.comment.Comment.refresh` (264:311) -- `praw.models.reddit.comment.CommentModeration.show` (336:350) - - -### Submission Management Component -This component manages Reddit submissions, providing functionalities for creating, retrieving, and moderating submissions. It includes methods for handling submission flair, setting contest mode, marking content as NSFW or spoiler, and managing sticky posts. - - -**Related Classes/Methods**: - -- `praw.models.reddit.submission.Submission` (395:916) -- `praw.models.reddit.submission.Submission.id_from_url` (452:483) -- `praw.models.reddit.submission.Submission.__init__` (566:598) -- `praw.models.reddit.submission.Submission._fetch` (710:723) -- `praw.models.reddit.submission.SubmissionModeration.contest_mode` (115:137) -- `praw.models.reddit.submission.SubmissionModeration.flair` (139:174) -- `praw.models.reddit.submission.SubmissionModeration.nsfw` (176:194) -- `praw.models.reddit.submission.SubmissionModeration.spoiler` (244:262) -- `praw.models.reddit.submission.SubmissionModeration.sticky` (264:297) - - -### Voting Mechanism Component -This component provides the core functionality for users to interact with the voting system on Reddit content. It allows for upvoting, downvoting, and clearing votes on various votable objects like submissions and comments. - - -**Related Classes/Methods**: - -- `praw.models.reddit.mixins.votable.VotableMixin` (8:92) -- `praw.models.reddit.mixins.votable.VotableMixin._vote` (11:12) -- `praw.models.reddit.mixins.votable.VotableMixin.clear_vote` (14:36) -- `praw.models.reddit.mixins.votable.VotableMixin.downvote` (38:64) -- `praw.models.reddit.mixins.votable.VotableMixin.upvote` (66:92) - - -### Moderation Mixin Component -This component provides a set of common moderation functionalities that can be applied to various 'Thing' objects (like comments and submissions) on Reddit. It includes methods for removing content and distinguishing posts. - - -**Related Classes/Methods**: - -- `praw.models.reddit.mixins.thing_moderation.ThingModerationMixin` (10:120) -- `praw.models.reddit.mixins.thing_moderation.ThingModerationMixin.remove` (full file reference) -- `praw.models.reddit.mixins.thing_moderation.ThingModerationMixin.undistinguish` (full file reference) - - -### Base List Component -This component provides the foundational structure for various list-like objects within PRAW, such as lists of drafts, moderated items, redditors, or trophies. It extends `PRAWBase` to offer common functionalities for managing collections of Reddit entities. - - -**Related Classes/Methods**: - -- `praw.models.list.base.BaseList` (15:54) - - - - -### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Specialized Content Features.md b/.codeboarding/Specialized Content Features.md deleted file mode 100644 index 4927e5414..000000000 --- a/.codeboarding/Specialized Content Features.md +++ /dev/null @@ -1,204 +0,0 @@ -```mermaid -graph LR - Reddit_Client["Reddit Client"] - Live_Thread_System["Live Thread System"] - Multireddit_System["Multireddit System"] - Collection_System["Collection System"] - Base_API_Models["Base API Models"] - Content_Listing_Streaming["Content Listing & Streaming"] - Reddit_Entities["Reddit Entities"] - Exception_Handling["Exception Handling"] - Specialized_Content_Features["Specialized Content Features"] - Reddit_Client -- "initializes helpers for" --> Live_Thread_System - Reddit_Client -- "initializes helpers for" --> Multireddit_System - Reddit_Client -- "initializes helpers for" --> Collection_System - Reddit_Client -- "utilizes" --> Base_API_Models - Reddit_Client -- "creates instances of" --> Reddit_Entities - Reddit_Client -- "handles" --> Exception_Handling - Live_Thread_System -- "inherits from" --> Base_API_Models - Live_Thread_System -- "generates" --> Content_Listing_Streaming - Multireddit_System -- "inherits from" --> Base_API_Models - Multireddit_System -- "streams content via" --> Content_Listing_Streaming - Collection_System -- "inherits from" --> Base_API_Models - Collection_System -- "manages" --> Reddit_Entities - Content_Listing_Streaming -- "produces" --> Reddit_Entities - Specialized_Content_Features -- "encompasses" --> Live_Thread_System - Specialized_Content_Features -- "encompasses" --> Multireddit_System - Specialized_Content_Features -- "encompasses" --> Collection_System -``` -[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) - -## Component Details - -This graph illustrates the architecture of the PRAW library, focusing on how it manages various Reddit functionalities. The core `Reddit Client` component acts as the central entry point, handling API interactions and initializing helpers for specialized content types. These specialized content types, including `Live Thread System`, `Multireddit System`, and `Collection System`, are encapsulated within the `Specialized Content Features` component, providing dedicated interfaces for their unique structures and functionalities. All these systems leverage `Base API Models` for fundamental operations and interact with `Reddit Entities` to represent core Reddit objects. `Content Listing & Streaming` provides mechanisms for iterating and streaming data, while `Exception Handling` ensures robust error management across the library. - -### Reddit Client -The central class for interacting with the Reddit API, responsible for initialization, configuration, request handling, and providing access to various Reddit entities. - - -**Related Classes/Methods**: - -- `praw.reddit.Reddit` (57:901) -- `praw.reddit.Reddit.__init__` (114:386) -- `praw.reddit.Reddit._objectify_request` (435:469) -- `praw.reddit.Reddit.request` (821:876) -- `praw.reddit.Reddit.info` (641:720) -- `praw.reddit.Reddit.post` (743:789) -- `praw.reddit.Reddit.get` (627:639) -- `praw.reddit.Reddit.delete` (598:617) -- `praw.reddit.Reddit.patch` (722:741) -- `praw.reddit.Reddit.put` (791:808) -- `praw.reddit.Reddit.comment` (582:596) -- `praw.reddit.Reddit.domain` (619:625) -- `praw.reddit.Reddit.redditor` (810:819) -- `praw.reddit.Reddit.submission` (878:889) -- `praw.reddit.Reddit.username_available` (891:901) - - -### Live Thread System -This system encompasses all functionalities related to Reddit Live Threads, including their creation, retrieval, updates, contributor management, and streaming of live content. - - -**Related Classes/Methods**: - -- `praw.models.helpers.LiveHelper` (136:238) -- `praw.models.helpers.LiveHelper.__call__` (139:151) -- `praw.models.helpers.LiveHelper.info` (183:223) -- `praw.models.reddit.live.LiveThread` (261:471) -- `praw.models.reddit.live.LiveThread.__init__` (375:392) -- `praw.models.reddit.live.LiveThread._fetch` (394:399) -- `praw.models.reddit.live.LiveThread.contrib` (284:295) -- `praw.models.reddit.live.LiveThread.contributor` (298:313) -- `praw.models.reddit.live.LiveThread.stream` (316:338) -- `praw.models.reddit.live.LiveThread.__getitem__` (352:369) -- `praw.models.reddit.live.LiveThread.discussions` (404:426) -- `praw.models.reddit.live.LiveThread.updates` (446:471) -- `praw.models.reddit.live.LiveContributorRelationship` (22:258) -- `praw.models.reddit.live.LiveContributorRelationship.invite` (73:111) -- `praw.models.reddit.live.LiveContributorRelationship.update` (174:215) -- `praw.models.reddit.live.LiveContributorRelationship.update_invite` (217:258) -- `praw.models.reddit.live.LiveThreadContribution` (474:582) -- `praw.models.reddit.live.LiveThreadContribution.update` (523:582) -- `praw.models.reddit.live.LiveUpdate` (700:792) -- `praw.models.reddit.live.LiveUpdate.__init__` (743:780) -- `praw.models.reddit.live.LiveUpdate._fetch` (788:792) -- `praw.models.reddit.live.LiveUpdate.contrib` (724:736) -- `praw.models.reddit.live.LiveUpdate.__setattr__` (782:786) -- `praw.models.reddit.live.LiveThreadStream` (585:637) -- `praw.models.reddit.live.LiveThreadStream.updates` (605:637) - - -### Multireddit System -This system manages Reddit Multireddits, providing functionalities for creating, modifying, and retrieving multireddit content, as well as streaming from them. - - -**Related Classes/Methods**: - -- `praw.models.helpers.MultiredditHelper` (241:298) -- `praw.models.helpers.MultiredditHelper.__call__` (244:253) -- `praw.models.reddit.multi.Multireddit` (20:228) -- `praw.models.reddit.multi.Multireddit.__init__` (96:104) -- `praw.models.reddit.multi.Multireddit._fetch` (106:111) -- `praw.models.reddit.multi.Multireddit.add` (120:135) -- `praw.models.reddit.multi.Multireddit.copy` (137:161) -- `praw.models.reddit.multi.Multireddit.remove` (176:191) -- `praw.models.reddit.multi.Multireddit.stream` (72:94) -- `praw.models.reddit.multi.Multireddit.sluggify` (55:69) - - -### Collection System -This system handles Reddit Collections, including their creation, content management, and moderation functionalities. - - -**Related Classes/Methods**: - -- `praw.models.reddit.collections.Collection` (380:575) -- `praw.models.reddit.collections.Collection.__init__` (454:484) -- `praw.models.reddit.collections.Collection._fetch` (521:534) -- `praw.models.reddit.collections.Collection.mod` (422:438) -- `praw.models.reddit.collections.SubredditCollections` (291:377) -- `praw.models.reddit.collections.SubredditCollections.__init__` (352:360) -- `praw.models.reddit.collections.SubredditCollections.__call__` (316:350) -- `praw.models.reddit.collections.SubredditCollections.mod` (303:314) -- `praw.models.reddit.collections.CollectionModeration` (21:216) -- `praw.models.reddit.collections.CollectionModeration.__init__` (32:39) -- `praw.models.reddit.collections.CollectionModeration.add_post` (61:84) -- `praw.models.reddit.collections.CollectionModeration.remove_post` (102:125) -- `praw.models.reddit.collections.CollectionModeration.reorder` (127:147) -- `praw.models.reddit.collections.CollectionModeration._post_fullname` (41:59) -- `praw.models.reddit.collections.SubredditCollectionsModeration` (219:288) -- `praw.models.reddit.collections.SubredditCollectionsModeration.__init__` (230:238) - - -### Base API Models -This component provides the fundamental building blocks and common methods for various PRAW models, such as base initialization, URL parsing, and generic data fetching mechanisms. - - -**Related Classes/Methods**: - -- `praw.models.base.PRAWBase` (12:47) -- `praw.models.base.PRAWBase.__init__` (38:47) -- `praw.models.reddit.base.RedditBase` (16:90) -- `praw.models.reddit.base.RedditBase.__init__` (44:64) -- `praw.models.reddit.base.RedditBase._url_parts` (20:24) -- `praw.models.reddit.base.RedditBase._fetch_data` (81:84) -- `praw.models.reddit.base.RedditBase._fetch` (78:79) -- `praw.models.reddit.base.RedditBase._reset_attributes` (86:90) -- `praw.models.listing.mixins.subreddit.SubredditListingMixin` (49:73) -- `praw.models.listing.mixins.subreddit.SubredditListingMixin.__init__` (67:73) - - -### Content Listing & Streaming -This component is responsible for generating iterable listings of Reddit content and providing mechanisms for streaming real-time data from various sources. - - -**Related Classes/Methods**: - -- `praw.models.listing.generator.ListingGenerator` (17:103) -- `praw.models.util.stream_generator` (36:163) -- `praw.models.reddit.subreddit.SubredditStream` (full file reference) - - -### Reddit Entities -This component represents core Reddit entities such as Redditors (users) and Subreddits, encapsulating their properties and providing methods for interaction. - - -**Related Classes/Methods**: - -- `praw.models.reddit.redditor.Redditor` (21:409) -- `praw.models.reddit.subreddit.Subreddit` (full file reference) - - -### Exception Handling -This component defines and manages custom exceptions specific to the PRAW library, allowing for structured error handling within the application. - - -**Related Classes/Methods**: - -- `praw.exceptions.ClientException` (74:75) - - -### Specialized Content Features -Manages specialized content types on Reddit, including Live Threads, Multireddits, and Collections. It provides dedicated interfaces for interacting with these unique content structures and their specific functionalities. - - -**Related Classes/Methods**: - -- `praw.models.helpers.LiveHelper` (136:238) -- `praw.models.reddit.live.LiveContributorRelationship` (22:258) -- `praw.models.reddit.live.LiveThread` (261:471) -- `praw.models.reddit.live.LiveThreadContribution` (474:582) -- `praw.models.reddit.live.LiveThreadStream` (585:637) -- `praw.models.reddit.live.LiveUpdate` (700:792) -- `praw.models.reddit.live.LiveUpdateContribution` (640:697) -- `praw.models.helpers.MultiredditHelper` (241:298) -- `praw.models.reddit.multi.Multireddit` (20:228) -- `praw.models.reddit.collections.CollectionModeration` (21:216) -- `praw.models.reddit.collections.SubredditCollectionsModeration` (219:288) -- `praw.models.reddit.collections.SubredditCollections` (291:377) -- `praw.models.reddit.collections.Collection` (380:575) - - - - -### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/User & Community Management.md b/.codeboarding/User & Community Management.md deleted file mode 100644 index 9b62cc9b0..000000000 --- a/.codeboarding/User & Community Management.md +++ /dev/null @@ -1,172 +0,0 @@ -```mermaid -graph LR - RedditClientCore["RedditClientCore"] - UserAccountManagement["UserAccountManagement"] - RedditorInteraction["RedditorInteraction"] - SubredditManagement["SubredditManagement"] - ModerationTools["ModerationTools"] - SubredditWidgets["SubredditWidgets"] - ModmailConversations["ModmailConversations"] - SubredditContentManagement["SubredditContentManagement"] - ContentListingAndStreaming["ContentListingAndStreaming"] - RedditClientCore -- "initializes" --> UserAccountManagement - RedditClientCore -- "provides access to" --> UserAccountManagement - RedditClientCore -- "provides access to" --> RedditorInteraction - RedditClientCore -- "provides access to" --> SubredditManagement - RedditClientCore -- "provides access to" --> ModerationTools - UserAccountManagement -- "generates listings for" --> ContentListingAndStreaming - UserAccountManagement -- "interacts with" --> RedditorInteraction - RedditorInteraction -- "generates streams for" --> ContentListingAndStreaming - RedditorInteraction -- "is subject to moderation notes from" --> ModerationTools - SubredditManagement -- "generates streams for" --> ContentListingAndStreaming - SubredditManagement -- "is managed by" --> ModerationTools - SubredditManagement -- "manages" --> SubredditWidgets - SubredditManagement -- "handles modmail for" --> ModmailConversations - SubredditManagement -- "manages content aspects for" --> SubredditContentManagement - ModerationTools -- "generates moderation streams for" --> ContentListingAndStreaming - ModerationTools -- "applies to redditors" --> RedditorInteraction - ModerationTools -- "provides moderation capabilities for" --> SubredditManagement - SubredditWidgets -- "are managed by" --> SubredditManagement - ModmailConversations -- "are part of subreddit management" --> SubredditManagement - SubredditContentManagement -- "is managed by" --> SubredditManagement -``` -[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) - -## Component Details - -This comprehensive component provides all tools necessary for managing user accounts, interacting with individual Redditor profiles, and moderating subreddits. It covers user preferences, inbox management, subreddit creation, moderation tools (modmail, notes, rules, removal reasons, wiki pages, widgets, emojis), and relationships within communities. - -### RedditClientCore -This component serves as the primary interface for interacting with the Reddit API, initializing core functionalities and providing access points to various Reddit resources. - - -**Related Classes/Methods**: - -- `praw.reddit.Reddit` (57:901) -- `praw.praw.models.front.Front` (17:32) -- `praw.praw.models.auth.Auth` (11:125) - - -### UserAccountManagement -This component handles functionalities related to the authenticated user's account, including managing inbox messages, user preferences, and retrieving information about the user's contributions and moderation roles. - - -**Related Classes/Methods**: - -- `praw.praw.models.inbox.Inbox` (18:324) -- `praw.praw.models.user.User` (24:259) -- `praw.models.preferences.Preferences` (14:204) - - -### RedditorInteraction -This component provides methods for interacting with individual Reddit users (Redditors), such as retrieving user profiles, managing friendships, and accessing user-specific content streams. - - -**Related Classes/Methods**: - -- `praw.praw.models.redditors.Redditors` (26:104) -- `praw.praw.models.reddit.redditor.Redditor` (21:409) -- `praw.praw.models.reddit.redditor.RedditorStream` (412:457) -- `praw.praw.models.reddit.user_subreddit.UserSubreddit` (14:78) - - -### SubredditManagement -This component manages core aspects of subreddits, including their creation and general properties. - - -**Related Classes/Methods**: - -- `praw.praw.models.subreddits.Subreddits` (19:133) -- `praw.praw.models.helpers.SubredditHelper` (301:353) -- `praw.praw.models.reddit.subreddit.Subreddit` (200:350) -- `praw.praw.models.reddit.subreddit.SubredditRelationship` (500:520) - - -### ModerationTools -This component encapsulates various tools and functionalities for subreddit moderators, including managing moderation notes, defining and enforcing rules, handling removal reasons, and managing moderation-related relationships. - - -**Related Classes/Methods**: - -- `praw.praw.models.reddit.user_subreddit.UserSubredditModeration` (82:199) -- `praw.praw.models.reddit.subreddit.ModeratorRelationship` (683:800) -- `praw.praw.models.reddit.subreddit.SubredditModeration` (500:700) -- `praw.praw.models.reddit.subreddit.SubredditModerationStream` (703:740) -- `praw.praw.models.mod_notes.BaseModNotes` (22:271) -- `praw.praw.models.mod_notes.RedditorModNotes` (274:367) -- `praw.praw.models.mod_notes.SubredditModNotes` (370:463) -- `praw.praw.models.mod_notes.RedditModNotes` (466:682) -- `praw.praw.models.reddit.rules.Rule` (19:100) -- `praw.praw.models.reddit.rules.SubredditRules` (189:314) -- `praw.praw.models.reddit.rules.RuleModeration` (103:186) -- `praw.praw.models.reddit.rules.SubredditRulesModeration` (317:413) -- `praw.praw.models.reddit.removal_reasons.RemovalReason` (18:114) -- `praw.praw.models.reddit.removal_reasons.SubredditRemovalReasons` (117:223) - - -### SubredditWidgets -This component manages the creation, modification, and display of various widgets on subreddit sidebars and other areas. - - -**Related Classes/Methods**: - -- `praw.praw.models.reddit.widgets.SubredditWidgets` (177:361) -- `praw.praw.models.reddit.widgets.Widget` (364:395) -- `praw.praw.models.reddit.widgets.CustomWidget` (639:710) -- `praw.praw.models.reddit.widgets.ModeratorsWidget` (894:933) -- `praw.praw.models.reddit.widgets.RulesWidget` (623:640) -- `praw.praw.models.reddit.widgets.SubredditWidgetsModeration` (283:390) -- `praw.praw.models.reddit.widgets.ButtonWidget` (410:497) -- `praw.praw.models.reddit.widgets.Calendar` (500:571) -- `praw.praw.models.reddit.widgets.CommunityList` (574:636) -- `praw.praw.models.reddit.widgets.IDCard` (713:748) -- `praw.praw.models.reddit.widgets.ImageWidget` (751:820) -- `praw.praw.models.reddit.widgets.Menu` (823:891) -- `praw.praw.models.reddit.widgets.PostFlairWidget` (936:1000) -- `praw.praw.models.reddit.widgets.TextArea` (1000:1090) - - -### ModmailConversations -This component handles the management of modmail conversations, allowing moderators to read, reply to, and manage messages within the modmail system. - - -**Related Classes/Methods**: - -- `praw.praw.models.reddit.modmail.ModmailConversation` (28:325) -- `praw.praw.models.reddit.modmail.ModmailAction` (328:329) -- `praw.praw.models.reddit.modmail.ModmailMessage` (332:333) -- `praw.praw.models.reddit.subreddit.Modmail` (20:100) - - -### SubredditContentManagement -This component manages content-related aspects within a subreddit, including flair, stylesheets, wiki pages, and emojis. - - -**Related Classes/Methods**: - -- `praw.praw.models.reddit.subreddit.SubredditFlair` (200:350) -- `praw.praw.models.reddit.subreddit.SubredditFlairTemplates` (353:490) -- `praw.praw.models.reddit.subreddit.SubredditStylesheet` (563:680) -- `praw.praw.models.reddit.subreddit.SubredditWiki` (743:780) -- `praw.praw.models.reddit.wikipage.WikiPage` (146:314) -- `praw.praw.models.reddit.wikipage.WikiPageModeration` (19:143) -- `praw.praw.models.reddit.emoji.Emoji` (16:131) -- `praw.praw.models.reddit.emoji.SubredditEmoji` (134:234) - - -### ContentListingAndStreaming -This component is responsible for generating iterable listings of Reddit content (like posts, comments, users, subreddits) and providing real-time streams of new content. - - -**Related Classes/Methods**: - -- `praw.models.listing.generator.ListingGenerator` (17:103) -- `praw.models.util.stream_generator` (36:163) -- `praw.praw.models.reddit.subreddit.SubredditStream` (523:560) -- `praw.praw.models.reddit.redditor.RedditorStream` (412:457) -- `praw.praw.models.reddit.subreddit.SubredditModerationStream` (703:740) - - - - -### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/on_boarding.md b/.codeboarding/on_boarding.md deleted file mode 100644 index 463ea0b3d..000000000 --- a/.codeboarding/on_boarding.md +++ /dev/null @@ -1,190 +0,0 @@ -```mermaid -graph LR - PRAW_Core_API_Interaction["PRAW Core & API Interaction"] - Reddit_Data_Models["Reddit Data Models"] - Content_Listing_Management["Content & Listing Management"] - User_Community_Management["User & Community Management"] - Specialized_Content_Features["Specialized Content Features"] - Development_Build_Tools["Development & Build Tools"] - PRAW_Core_API_Interaction -- "communicates with" --> Reddit_Data_Models - PRAW_Core_API_Interaction -- "processes requests for" --> Content_Listing_Management - PRAW_Core_API_Interaction -- "processes requests for" --> User_Community_Management - PRAW_Core_API_Interaction -- "processes requests for" --> Specialized_Content_Features - Reddit_Data_Models -- "defines structure for" --> Content_Listing_Management - Reddit_Data_Models -- "defines structure for" --> User_Community_Management - Reddit_Data_Models -- "defines structure for" --> Specialized_Content_Features - Content_Listing_Management -- "utilizes" --> PRAW_Core_API_Interaction - Content_Listing_Management -- "generates" --> Reddit_Data_Models - User_Community_Management -- "utilizes" --> PRAW_Core_API_Interaction - User_Community_Management -- "operates on" --> Reddit_Data_Models - Specialized_Content_Features -- "utilizes" --> PRAW_Core_API_Interaction - Specialized_Content_Features -- "operates on" --> Reddit_Data_Models - Development_Build_Tools -- "analyzes" --> PRAW_Core_API_Interaction - Development_Build_Tools -- "tests" --> Reddit_Data_Models - click PRAW_Core_API_Interaction href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/praw/PRAW Core & API Interaction.md" "Details" - click Reddit_Data_Models href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/praw/Reddit Data Models.md" "Details" - click Content_Listing_Management href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/praw/Content & Listing Management.md" "Details" - click User_Community_Management href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/praw/User & Community Management.md" "Details" - click Specialized_Content_Features href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/praw/Specialized Content Features.md" "Details" - click Development_Build_Tools href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/praw/Development & Build Tools.md" "Details" -``` -[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) - -## Component Details - -The PRAW library provides a Pythonic interface to the Reddit API, enabling developers to interact with Reddit programmatically. The main flow involves a core API interaction component that handles requests and responses, utilizing data models to represent Reddit entities. Various management components then leverage this core and data models to handle specific functionalities like content listing, user interactions, community moderation, and specialized content features. Development tools support the library's maintenance and release processes. - -### PRAW Core & API Interaction -The foundational layer of the PRAW library, managing core interaction with the Reddit API. It handles client configuration, request objectification, and the processing of API responses, including error handling. It ensures all communications with Reddit are properly authenticated and formatted. - - -**Related Classes/Methods**: - -- `praw.praw.reddit.Reddit` (57:901) -- `praw.praw.objector.Objector` (17:263) -- `praw.praw.exceptions.MediaPostFailed` (158:167) -- `praw.praw.exceptions.RedditAPIException` (170:201) -- `praw.praw.config.Config` (27:173) -- `praw.praw.util.snake` (6:19) - - -### Reddit Data Models -Provides the fundamental base classes and mixins that define the structure and common behaviors of various Reddit entities (like submissions, comments, users, and subreddits). It serves as the blueprint for how PRAW represents data received from the Reddit API, enabling consistent attribute access and basic functionalities across different object types. - - -**Related Classes/Methods**: - -- `praw.praw.models.base.PRAWBase` (12:47) -- `praw.praw.models.reddit.base.RedditBase` (16:90) -- `praw.praw.models.reddit.mixins.votable.VotableMixin` (8:92) -- `praw.praw.models.reddit.mixins.ThingModerationMixin` (10:120) -- `praw.praw.models.list.base.BaseList` (15:54) - - -### Content & Listing Management -Responsible for efficiently retrieving and iterating through various types of content listings from Reddit, such as hot, new, or top posts. It also provides utilities for real-time data streams and handles the creation, retrieval, and general management of Reddit submissions (posts) and comments, including drafts and poll data. - - -**Related Classes/Methods**: - -- `praw.praw.models.listing.generator.ListingGenerator` (17:103) -- `praw.praw.models.listing.domain.DomainListing` (14:25) -- `praw.praw.models.listing.mixins.redditor.SubListing` (18:32) -- `praw.praw.models.listing.mixins.redditor.RedditorListingMixin` (35:185) -- `praw.praw.models.listing.mixins.subreddit.CommentHelper` (20:46) -- `praw.praw.models.listing.mixins.subreddit.SubredditListingMixin` (49:73) -- `praw.praw.models.listing.mixins.rising.RisingListingMixin` (17:34) -- `praw.praw.models.listing.mixins.base.BaseListingMixin` (15:149) -- `praw.praw.models.listing.mixins.submission.SubmissionListingMixin` (17:42) -- `praw.praw.models.util` (10:190) -- `praw.praw.models.comment_forest.CommentForest` (15:202) -- `praw.praw.models.reddit.comment.Comment` (19:311) -- `praw.praw.models.reddit.comment.CommentModeration` (314:350) -- `praw.praw.models.reddit.more.MoreComments` (14:87) -- `praw.praw.models.reddit.submission.Submission` (395:916) -- `praw.praw.models.reddit.submission.SubmissionFlair` (40:90) -- `praw.praw.models.reddit.submission.SubmissionModeration` (93:392) -- `praw.praw.models.helpers.DraftHelper` (20:133) -- `praw.praw.models.reddit.draft.Draft` (17:292) -- `praw.praw.models.reddit.poll.PollData` (47:112) -- `praw.praw.models.reddit.poll.PollOption` (11:44) - - -### User & Community Management -This comprehensive component provides all tools necessary for managing user accounts, interacting with individual Redditor profiles, and moderating subreddits. It covers user preferences, inbox management, subreddit creation, moderation tools (modmail, notes, rules, removal reasons, wiki pages, widgets, emojis), and relationships within communities. - - -**Related Classes/Methods**: - -- `praw.praw.models.front.Front` (17:32) -- `praw.praw.models.inbox.Inbox` (18:324) -- `praw.praw.models.auth.Auth` (11:125) -- `praw.praw.models.user.User` (24:259) -- `praw.praw.models.redditors.Redditors` (26:104) -- `praw.praw.models.reddit.redditor.Redditor` (21:409) -- `praw.praw.models.reddit.redditor.RedditorStream` (412:457) -- `praw.praw.models.reddit.user_subreddit.UserSubreddit` (14:78) -- `praw.praw.models.reddit.user_subreddit.UserSubredditModeration` (82:199) -- `praw.praw.models.subreddits.Subreddits` (19:133) -- `praw.praw.models.helpers.SubredditHelper` (301:353) -- `praw.praw.models.reddit.subreddit.Subreddit` (200:350) -- `praw.praw.models.reddit.subreddit.SubredditRelationship` (500:520) -- `praw.praw.models.reddit.subreddit.SubredditStream` (523:560) -- `praw.praw.models.reddit.subreddit.SubredditStylesheet` (563:680) -- `praw.praw.models.reddit.subreddit.ModeratorRelationship` (683:800) -- `praw.praw.models.reddit.subreddit.Modmail` (20:100) -- `praw.praw.models.reddit.subreddit.SubredditFlair` (200:350) -- `praw.praw.models.reddit.subreddit.SubredditFlairTemplates` (353:490) -- `praw.praw.models.reddit.subreddit.SubredditModeration` (500:700) -- `praw.praw.models.reddit.subreddit.SubredditModerationStream` (703:740) -- `praw.praw.models.reddit.subreddit.SubredditWiki` (743:780) -- `praw.praw.models.mod_notes.BaseModNotes` (22:271) -- `praw.praw.models.mod_notes.RedditorModNotes` (274:367) -- `praw.praw.models.mod_notes.SubredditModNotes` (370:463) -- `praw.praw.models.mod_notes.RedditModNotes` (466:682) -- `praw.praw.models.reddit.modmail.ModmailConversation` (28:325) -- `praw.praw.models.reddit.modmail.ModmailAction` (328:329) -- `praw.praw.models.reddit.modmail.ModmailMessage` (332:333) -- `praw.praw.models.reddit.rules.Rule` (19:100) -- `praw.praw.models.reddit.rules.SubredditRules` (189:314) -- `praw.praw.models.reddit.rules.RuleModeration` (103:186) -- `praw.praw.models.reddit.rules.SubredditRulesModeration` (317:413) -- `praw.praw.models.reddit.removal_reasons.RemovalReason` (18:114) -- `praw.praw.models.reddit.removal_reasons.SubredditRemovalReasons` (117:223) -- `praw.praw.models.reddit.wikipage.WikiPage` (146:314) -- `praw.praw.models.reddit.wikipage.WikiPageModeration` (19:143) -- `praw.praw.models.reddit.emoji.Emoji` (16:131) -- `praw.praw.models.reddit.emoji.SubredditEmoji` (134:234) -- `praw.praw.models.reddit.widgets.SubredditWidgets` (177:361) -- `praw.praw.models.reddit.widgets.Widget` (364:395) -- `praw.praw.models.reddit.widgets.CustomWidget` (639:710) -- `praw.praw.models.reddit.widgets.ModeratorsWidget` (894:933) -- `praw.praw.models.reddit.widgets.RulesWidget` (623:640) -- `praw.praw.models.reddit.widgets.SubredditWidgetsModeration` (283:390) -- `praw.praw.models.reddit.widgets.ButtonWidget` (410:497) -- `praw.praw.models.reddit.widgets.Calendar` (500:571) -- `praw.praw.models.reddit.widgets.CommunityList` (574:636) -- `praw.praw.models.reddit.widgets.IDCard` (713:748) -- `praw.praw.models.reddit.widgets.ImageWidget` (751:820) -- `praw.praw.models.reddit.widgets.Menu` (823:891) -- `praw.praw.models.reddit.widgets.PostFlairWidget` (936:1000) -- `praw.praw.models.reddit.widgets.TextArea` (1000:1090) - - -### Specialized Content Features -Manages specialized content types on Reddit, including Live Threads, Multireddits, and Collections. It provides dedicated interfaces for interacting with these unique content structures and their specific functionalities. - - -**Related Classes/Methods**: - -- `praw.praw.models.helpers.LiveHelper` (136:238) -- `praw.praw.models.reddit.live.LiveContributorRelationship` (22:258) -- `praw.praw.models.reddit.live.LiveThread` (261:471) -- `praw.praw.models.reddit.live.LiveThreadContribution` (474:582) -- `praw.praw.models.reddit.live.LiveThreadStream` (585:637) -- `praw.praw.models.reddit.live.LiveUpdate` (700:792) -- `praw.praw.models.reddit.live.LiveUpdateContribution` (640:697) -- `praw.praw.models.helpers.MultiredditHelper` (241:298) -- `praw.praw.models.reddit.multi.Multireddit` (20:228) -- `praw.praw.models.reddit.collections.CollectionModeration` (21:216) -- `praw.praw.models.reddit.collections.SubredditCollectionsModeration` (219:288) -- `praw.praw.models.reddit.collections.SubredditCollections` (291:377) -- `praw.praw.models.reddit.collections.Collection` (380:575) - - -### Development & Build Tools -This component comprises scripts and utilities primarily used for the development, testing, and release management of the PRAW library itself. It includes tools for static analysis, unit testing, and version control, and is not part of the library's runtime functionality. - - -**Related Classes/Methods**: - -- `praw.pre_push` (2:80) -- `praw.tools.static_word_checks` (5:100) -- `praw.tools.check_documentation` (5:70) -- `praw.tools.set_active_docs` (5:80) -- `praw.tools.set_version` (5:100) - - - - -### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file From 65be4da5789f5d7fe543d234e14c71e79b9c0176 Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Mon, 1 Sep 2025 17:14:21 +0000 Subject: [PATCH 04/23] docs: update codeboarding documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 📚 Documentation Update This commit contains updated documentation files fetched from the CodeBoarding service. ### 📊 Summary - Documentation files created/updated: 6 - JSON files created/updated: 7 - Documentation directory: .codeboarding/ - JSON directory: .codeboarding/ - Output format: .md - Repository analyzed: https://github.com/CodeBoarding/praw - Source branch: main - Target branch: main 🤖 This commit was automatically generated by the CodeBoarding documentation update workflow. --- .codeboarding/API_Client_Core.json | 184 +++++++++++++++ .codeboarding/API_Client_Core.md | 100 +++++++++ .codeboarding/Exception_Handling.json | 98 ++++++++ .codeboarding/Exception_Handling.md | 68 ++++++ .codeboarding/Listing_Stream_Processors.json | 143 ++++++++++++ .codeboarding/Listing_Stream_Processors.md | 92 ++++++++ .../Object_Transformation_Layer.json | 92 ++++++++ .codeboarding/Object_Transformation_Layer.md | 67 ++++++ .codeboarding/Reddit_Data_Models.json | 146 ++++++++++++ .codeboarding/Reddit_Data_Models.md | 100 +++++++++ .codeboarding/analysis.json | 211 ++++++++++++++++++ .codeboarding/codeboarding_version.json | 4 + .codeboarding/on_boarding.md | 101 +++++++++ 13 files changed, 1406 insertions(+) create mode 100644 .codeboarding/API_Client_Core.json create mode 100644 .codeboarding/API_Client_Core.md create mode 100644 .codeboarding/Exception_Handling.json create mode 100644 .codeboarding/Exception_Handling.md create mode 100644 .codeboarding/Listing_Stream_Processors.json create mode 100644 .codeboarding/Listing_Stream_Processors.md create mode 100644 .codeboarding/Object_Transformation_Layer.json create mode 100644 .codeboarding/Object_Transformation_Layer.md create mode 100644 .codeboarding/Reddit_Data_Models.json create mode 100644 .codeboarding/Reddit_Data_Models.md create mode 100644 .codeboarding/analysis.json create mode 100644 .codeboarding/codeboarding_version.json create mode 100644 .codeboarding/on_boarding.md diff --git a/.codeboarding/API_Client_Core.json b/.codeboarding/API_Client_Core.json new file mode 100644 index 000000000..5c1fbdbad --- /dev/null +++ b/.codeboarding/API_Client_Core.json @@ -0,0 +1,184 @@ +{ + "description": "The PRAW Reddit API client is structured around the `API Client Core`, which serves as the primary interface for users. This core is set up by the `Client Initializer`, configuring essential components like the HTTP client and response parsing. User interactions, such as fetching data or creating posts, are handled by `API Operation Methods`. These methods delegate the actual HTTP communication to the `Request Executor`, which may consult the `Async Checker` for proper asynchronous execution. Upon receiving a raw response, the `Request Executor` passes it to the `Response Objectifier` for transformation into structured Python objects, which are then returned to the `API Operation Methods`. Throughout this process, the `Rate Limit Manager` is consulted to ensure adherence to Reddit's API usage policies, with the `API Client Core` overseeing and managing these interactions.", + "components": [ + { + "name": "API Client Core", + "description": "Serves as the main entry point for users to interact with the Reddit API. It orchestrates all underlying operations, manages the client's state, and exposes a high-level, object-oriented interface.", + "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 + } + ], + "can_expand": true + }, + { + "name": "Client Initializer", + "description": "Sets up the API Client Core instance, including configuring the underlying HTTP client (prawcore) and the response objectification mechanism. It integrates `prawcore` for HTTP requests and the `Objector` for response parsing.", + "referenced_source_code": [ + { + "qualified_name": "praw.reddit.Reddit.__init__", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 0, + "reference_end_line": 0 + }, + { + "qualified_name": "praw.reddit._prepare_prawcore", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 527, + "reference_end_line": 546 + }, + { + "qualified_name": "praw.reddit._prepare_objector", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 479, + "reference_end_line": 525 + } + ], + "can_expand": true + }, + { + "name": "Request Executor", + "description": "Executes the raw HTTP requests to the Reddit API, handling the low-level communication details.", + "referenced_source_code": [ + { + "qualified_name": "praw.reddit.Reddit.request", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 0, + "reference_end_line": 0 + } + ], + "can_expand": false + }, + { + "name": "Response Objectifier", + "description": "Transforms the raw JSON responses from the API into structured PRAW Python objects, making them easier to consume and work with.", + "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 + } + ], + "can_expand": true + }, + { + "name": "Rate Limit Manager", + "description": "Monitors and enforces Reddit's API rate limits, pausing requests when necessary to prevent exceeding usage quotas and ensuring compliance.", + "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 + } + ], + "can_expand": false + }, + { + "name": "API Operation Methods", + "description": "Provide specific, high-level methods for common API operations (e.g., fetching data, creating posts, deleting resources), abstracting the underlying request and response handling details from the end-user.", + "referenced_source_code": [ + { + "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.post", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 0, + "reference_end_line": 0 + }, + { + "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.patch", + "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 + } + ], + "can_expand": true + }, + { + "name": "Async Checker", + "description": "Manages and verifies the asynchronous context for operations, ensuring proper execution in async environments.", + "referenced_source_code": [ + { + "qualified_name": "praw.reddit._check_for_async", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 388, + "reference_end_line": 411 + } + ], + "can_expand": false + } + ], + "components_relations": [ + { + "relation": "initializes", + "src_name": "Client Initializer", + "dst_name": "API Client Core" + }, + { + "relation": "manages", + "src_name": "API Client Core", + "dst_name": "Request Executor" + }, + { + "relation": "manages", + "src_name": "API Client Core", + "dst_name": "Response Objectifier" + }, + { + "relation": "manages", + "src_name": "API Client Core", + "dst_name": "Rate Limit Manager" + }, + { + "relation": "exposes", + "src_name": "API Client Core", + "dst_name": "API Operation Methods" + }, + { + "relation": "invokes", + "src_name": "API Operation Methods", + "dst_name": "Request Executor" + }, + { + "relation": "checks", + "src_name": "Request Executor", + "dst_name": "Async Checker" + }, + { + "relation": "returns raw response to", + "src_name": "Request Executor", + "dst_name": "Response Objectifier" + }, + { + "relation": "transforms for", + "src_name": "Response Objectifier", + "dst_name": "API Operation Methods" + }, + { + "relation": "consults", + "src_name": "API Operation Methods", + "dst_name": "Rate Limit Manager" + } + ] +} diff --git a/.codeboarding/API_Client_Core.md b/.codeboarding/API_Client_Core.md new file mode 100644 index 000000000..418e5ec0f --- /dev/null +++ b/.codeboarding/API_Client_Core.md @@ -0,0 +1,100 @@ +```mermaid +graph LR + API_Client_Core["API Client Core"] + Client_Initializer["Client Initializer"] + Request_Executor["Request Executor"] + Response_Objectifier["Response Objectifier"] + Rate_Limit_Manager["Rate Limit Manager"] + API_Operation_Methods["API Operation Methods"] + Async_Checker["Async Checker"] + Client_Initializer -- "initializes" --> API_Client_Core + API_Client_Core -- "manages" --> Request_Executor + API_Client_Core -- "manages" --> Response_Objectifier + API_Client_Core -- "manages" --> Rate_Limit_Manager + API_Client_Core -- "exposes" --> API_Operation_Methods + API_Operation_Methods -- "invokes" --> Request_Executor + Request_Executor -- "checks" --> Async_Checker + Request_Executor -- "returns raw response to" --> Response_Objectifier + Response_Objectifier -- "transforms for" --> API_Operation_Methods + API_Operation_Methods -- "consults" --> Rate_Limit_Manager + click API_Client_Core href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/API_Client_Core.md" "Details" +``` + +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Details + +The PRAW Reddit API client is structured around the `API Client Core`, which serves as the primary interface for users. This core is set up by the `Client Initializer`, configuring essential components like the HTTP client and response parsing. User interactions, such as fetching data or creating posts, are handled by `API Operation Methods`. These methods delegate the actual HTTP communication to the `Request Executor`, which may consult the `Async Checker` for proper asynchronous execution. Upon receiving a raw response, the `Request Executor` passes it to the `Response Objectifier` for transformation into structured Python objects, which are then returned to the `API Operation Methods`. Throughout this process, the `Rate Limit Manager` is consulted to ensure adherence to Reddit's API usage policies, with the `API Client Core` overseeing and managing these interactions. + +### API Client Core [[Expand]](./API_Client_Core.md) +Serves as the main entry point for users to interact with the Reddit API. It orchestrates all underlying operations, manages the client's state, and exposes a high-level, object-oriented interface. + + +**Related Classes/Methods**: + +- `praw.reddit.Reddit`:57-901 + + +### Client Initializer +Sets up the API Client Core instance, including configuring the underlying HTTP client (prawcore) and the response objectification mechanism. It integrates `prawcore` for HTTP requests and the `Objector` for response parsing. + + +**Related Classes/Methods**: + +- `praw.reddit.Reddit.__init__` +- `praw.reddit._prepare_prawcore`:527-546 +- `praw.reddit._prepare_objector`:479-525 + + +### Request Executor +Executes the raw HTTP requests to the Reddit API, handling the low-level communication details. + + +**Related Classes/Methods**: + +- `praw.reddit.Reddit.request` + + +### Response Objectifier +Transforms the raw JSON responses from the API into structured PRAW Python objects, making them easier to consume and work with. + + +**Related Classes/Methods**: + +- `praw.reddit.Reddit._objectify_request` + + +### Rate Limit Manager +Monitors and enforces Reddit's API rate limits, pausing requests when necessary to prevent exceeding usage quotas and ensuring compliance. + + +**Related Classes/Methods**: + +- `praw.reddit.Reddit._handle_rate_limit` + + +### API Operation Methods +Provide specific, high-level methods for common API operations (e.g., fetching data, creating posts, deleting resources), abstracting the underlying request and response handling details from the end-user. + + +**Related Classes/Methods**: + +- `praw.reddit.Reddit.get` +- `praw.reddit.Reddit.post` +- `praw.reddit.Reddit.delete` +- `praw.reddit.Reddit.patch` +- `praw.reddit.Reddit.put` + + +### Async Checker +Manages and verifies the asynchronous context for operations, ensuring proper execution in async environments. + + +**Related Classes/Methods**: + +- `praw.reddit._check_for_async`:388-411 + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) diff --git a/.codeboarding/Exception_Handling.json b/.codeboarding/Exception_Handling.json new file mode 100644 index 000000000..2c1ddc23d --- /dev/null +++ b/.codeboarding/Exception_Handling.json @@ -0,0 +1,98 @@ +{ + "description": "The `Exception Handling` subsystem is encapsulated within the `praw.exceptions` module, primarily defined by the `praw/praw/exceptions.py` file. It provides a dedicated mechanism for handling and representing errors specific to the PRAW library and the Reddit API.", + "components": [ + { + "name": "PRAWException", + "description": "The foundational base class for all custom exceptions within the PRAW library. It ensures a consistent interface and common attributes for all PRAW-specific errors, acting as the root of the exception hierarchy.", + "referenced_source_code": [ + { + "qualified_name": "PRAWException", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py", + "reference_start_line": 14, + "reference_end_line": 15 + } + ], + "can_expand": false + }, + { + "name": "Specific PRAW Exception Classes", + "description": "A set of specialized exception classes (e.g., `APIException`, `ClientException`) that inherit from `PRAWException`. These classes represent distinct error conditions, such as those returned by the Reddit API or client-side operational failures, and encapsulate parsed error details for specific contexts.", + "referenced_source_code": [ + { + "qualified_name": "APIException", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py", + "reference_start_line": 170, + "reference_end_line": 201 + }, + { + "qualified_name": "ClientException", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py", + "reference_start_line": 74, + "reference_end_line": 75 + } + ], + "can_expand": false + }, + { + "name": "RedditErrorItem", + "description": "A lightweight data structure that encapsulates the details of a single error item. It stores parsed information such as the error message, associated field, and type, as extracted from raw API responses.", + "referenced_source_code": [ + { + "qualified_name": "RedditErrorItem", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py", + "reference_start_line": 18, + "reference_end_line": 71 + } + ], + "can_expand": false + }, + { + "name": "parse_exception_list", + "description": "A utility function responsible for processing raw error data, typically a list of error messages or codes received from Reddit API responses. It transforms this raw data into a structured collection of `RedditErrorItem` objects.", + "referenced_source_code": [ + { + "qualified_name": "parse_exception_list", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py", + "reference_start_line": 173, + "reference_end_line": 189 + } + ], + "can_expand": false + }, + { + "name": "error_message", + "description": "A utility function dedicated to formatting a list of `RedditErrorItem` objects into a concise and informative error string. This string is suitable for display to developers or for logging purposes.", + "referenced_source_code": [ + { + "qualified_name": "error_message", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py", + "reference_start_line": 21, + "reference_end_line": 29 + } + ], + "can_expand": false + } + ], + "components_relations": [ + { + "relation": "inherits from", + "src_name": "Specific PRAW Exception Classes", + "dst_name": "PRAWException" + }, + { + "relation": "invokes", + "src_name": "Specific PRAW Exception Classes", + "dst_name": "parse_exception_list" + }, + { + "relation": "calls", + "src_name": "Specific PRAW Exception Classes", + "dst_name": "error_message" + }, + { + "relation": "creates and returns", + "src_name": "parse_exception_list", + "dst_name": "RedditErrorItem" + } + ] +} diff --git a/.codeboarding/Exception_Handling.md b/.codeboarding/Exception_Handling.md new file mode 100644 index 000000000..d531c0426 --- /dev/null +++ b/.codeboarding/Exception_Handling.md @@ -0,0 +1,68 @@ +```mermaid +graph LR + PRAWException["PRAWException"] + Specific_PRAW_Exception_Classes["Specific PRAW Exception Classes"] + RedditErrorItem["RedditErrorItem"] + parse_exception_list["parse_exception_list"] + error_message["error_message"] + Specific_PRAW_Exception_Classes -- "inherits from" --> PRAWException + Specific_PRAW_Exception_Classes -- "invokes" --> parse_exception_list + Specific_PRAW_Exception_Classes -- "calls" --> error_message + parse_exception_list -- "creates and returns" --> RedditErrorItem +``` + +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Details + +The `Exception Handling` subsystem is encapsulated within the `praw.exceptions` module, primarily defined by the `praw/praw/exceptions.py` file. It provides a dedicated mechanism for handling and representing errors specific to the PRAW library and the Reddit API. + +### PRAWException +The foundational base class for all custom exceptions within the PRAW library. It ensures a consistent interface and common attributes for all PRAW-specific errors, acting as the root of the exception hierarchy. + + +**Related Classes/Methods**: + +- `PRAWException`:14-15 + + +### Specific PRAW Exception Classes +A set of specialized exception classes (e.g., `APIException`, `ClientException`) that inherit from `PRAWException`. These classes represent distinct error conditions, such as those returned by the Reddit API or client-side operational failures, and encapsulate parsed error details for specific contexts. + + +**Related Classes/Methods**: + +- `APIException`:170-201 +- `ClientException`:74-75 + + +### RedditErrorItem +A lightweight data structure that encapsulates the details of a single error item. It stores parsed information such as the error message, associated field, and type, as extracted from raw API responses. + + +**Related Classes/Methods**: + +- `RedditErrorItem`:18-71 + + +### parse_exception_list +A utility function responsible for processing raw error data, typically a list of error messages or codes received from Reddit API responses. It transforms this raw data into a structured collection of `RedditErrorItem` objects. + + +**Related Classes/Methods**: + +- `parse_exception_list`:173-189 + + +### error_message +A utility function dedicated to formatting a list of `RedditErrorItem` objects into a concise and informative error string. This string is suitable for display to developers or for logging purposes. + + +**Related Classes/Methods**: + +- `error_message`:21-29 + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) diff --git a/.codeboarding/Listing_Stream_Processors.json b/.codeboarding/Listing_Stream_Processors.json new file mode 100644 index 000000000..9b3574709 --- /dev/null +++ b/.codeboarding/Listing_Stream_Processors.json @@ -0,0 +1,143 @@ +{ + "description": "This subsystem is responsible for abstracting the complexities of consuming data from the Reddit API, specifically handling paginated \"listings\" (e.g., posts in a subreddit) and continuous \"streams\" of new data (e.g., new comments). It ensures efficient data retrieval, manages pagination state, handles item uniqueness in streams, and implements robust backoff strategies to respect API rate limits.", + "components": [ + { + "name": "ListingGenerator", + "description": "Provides an iterable interface for consuming paginated API responses. It manages the state of pagination, such as the `_after` parameter, to fetch subsequent batches of data seamlessly.", + "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 + } + ], + "can_expand": false + }, + { + "name": "ListingBatchFetcher", + "description": "Responsible for fetching a single batch of items from the Reddit API using the underlying `Reddit` client. It utilizes the pagination state provided by `ListingGenerator` to request the correct segment of data.", + "referenced_source_code": [ + { + "qualified_name": "ListingBatchFetcher", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py", + "reference_start_line": 1, + "reference_end_line": 1000 + } + ], + "can_expand": true + }, + { + "name": "ListingDataExtractor", + "description": "Parses the raw JSON response received from the API, isolating and returning the actual list of data objects (e.g., posts, comments) from the API's wrapper structure.", + "referenced_source_code": [ + { + "qualified_name": "ListingDataExtractor", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py", + "reference_start_line": 1, + "reference_end_line": 1000 + } + ], + "can_expand": true + }, + { + "name": "ListingParameterMixin", + "description": "Provides common methods for constructing API paths and parameters required for various types of listings. This ensures consistency and reusability across different listing endpoints.", + "referenced_source_code": [ + { + "qualified_name": "ListingParameterMixin", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/mixins/base.py", + "reference_start_line": 1, + "reference_end_line": 1000 + } + ], + "can_expand": false + }, + { + "name": "StreamProcessor", + "description": "Implements the foundational logic for consuming continuous data streams from the Reddit API. It manages the overall flow, including delays between requests and ensuring resilient fetching.", + "referenced_source_code": [ + { + "qualified_name": "StreamProcessor", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/util.py", + "reference_start_line": 1, + "reference_end_line": 1000 + } + ], + "can_expand": true + }, + { + "name": "StreamUniquenessManager", + "description": "Maintains a limited set of recently seen items to ensure uniqueness within a data stream. This prevents reprocessing of duplicate items, which is crucial for real-time data consumption.", + "referenced_source_code": [ + { + "qualified_name": "StreamUniquenessManager", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/util.py", + "reference_start_line": 1, + "reference_end_line": 1000 + } + ], + "can_expand": false + }, + { + "name": "StreamBackoffHandler", + "description": "Implements an exponential backoff strategy to manage delays between stream requests. This is critical for respecting API rate limits and preventing excessive requests that could lead to temporary bans.", + "referenced_source_code": [ + { + "qualified_name": "StreamBackoffHandler", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/util.py", + "reference_start_line": 1, + "reference_end_line": 1000 + } + ], + "can_expand": false + } + ], + "components_relations": [ + { + "relation": "initiates data retrieval by calling", + "src_name": "ListingGenerator", + "dst_name": "ListingBatchFetcher" + }, + { + "relation": "fetches data and returns it to", + "src_name": "ListingBatchFetcher", + "dst_name": "ListingGenerator" + }, + { + "relation": "invokes", + "src_name": "ListingBatchFetcher", + "dst_name": "ListingDataExtractor" + }, + { + "relation": "provides the extracted list of items back to", + "src_name": "ListingDataExtractor", + "dst_name": "ListingBatchFetcher" + }, + { + "relation": "is utilized by", + "src_name": "ListingParameterMixin", + "dst_name": "ListingBatchFetcher" + }, + { + "relation": "utilizes", + "src_name": "StreamProcessor", + "dst_name": "StreamUniquenessManager" + }, + { + "relation": "provides uniqueness checks for", + "src_name": "StreamUniquenessManager", + "dst_name": "StreamProcessor" + }, + { + "relation": "consults", + "src_name": "StreamProcessor", + "dst_name": "StreamBackoffHandler" + }, + { + "relation": "provides backoff durations to", + "src_name": "StreamBackoffHandler", + "dst_name": "StreamProcessor" + } + ] +} diff --git a/.codeboarding/Listing_Stream_Processors.md b/.codeboarding/Listing_Stream_Processors.md new file mode 100644 index 000000000..a266e5ddc --- /dev/null +++ b/.codeboarding/Listing_Stream_Processors.md @@ -0,0 +1,92 @@ +```mermaid +graph LR + ListingGenerator["ListingGenerator"] + ListingBatchFetcher["ListingBatchFetcher"] + ListingDataExtractor["ListingDataExtractor"] + ListingParameterMixin["ListingParameterMixin"] + StreamProcessor["StreamProcessor"] + StreamUniquenessManager["StreamUniquenessManager"] + StreamBackoffHandler["StreamBackoffHandler"] + ListingGenerator -- "initiates data retrieval by calling" --> ListingBatchFetcher + ListingBatchFetcher -- "fetches data and returns it to" --> ListingGenerator + ListingBatchFetcher -- "invokes" --> ListingDataExtractor + ListingDataExtractor -- "provides the extracted list of items back to" --> ListingBatchFetcher + ListingParameterMixin -- "is utilized by" --> ListingBatchFetcher + StreamProcessor -- "utilizes" --> StreamUniquenessManager + StreamUniquenessManager -- "provides uniqueness checks for" --> StreamProcessor + StreamProcessor -- "consults" --> StreamBackoffHandler + StreamBackoffHandler -- "provides backoff durations to" --> StreamProcessor +``` + +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Details + +This subsystem is responsible for abstracting the complexities of consuming data from the Reddit API, specifically handling paginated "listings" (e.g., posts in a subreddit) and continuous "streams" of new data (e.g., new comments). It ensures efficient data retrieval, manages pagination state, handles item uniqueness in streams, and implements robust backoff strategies to respect API rate limits. + +### ListingGenerator +Provides an iterable interface for consuming paginated API responses. It manages the state of pagination, such as the `_after` parameter, to fetch subsequent batches of data seamlessly. + + +**Related Classes/Methods**: + +- `ListingGenerator`:17-103 + + +### ListingBatchFetcher +Responsible for fetching a single batch of items from the Reddit API using the underlying `Reddit` client. It utilizes the pagination state provided by `ListingGenerator` to request the correct segment of data. + + +**Related Classes/Methods**: + +- `ListingBatchFetcher`:1-1000 + + +### ListingDataExtractor +Parses the raw JSON response received from the API, isolating and returning the actual list of data objects (e.g., posts, comments) from the API's wrapper structure. + + +**Related Classes/Methods**: + +- `ListingDataExtractor`:1-1000 + + +### ListingParameterMixin +Provides common methods for constructing API paths and parameters required for various types of listings. This ensures consistency and reusability across different listing endpoints. + + +**Related Classes/Methods**: + +- `ListingParameterMixin`:1-1000 + + +### StreamProcessor +Implements the foundational logic for consuming continuous data streams from the Reddit API. It manages the overall flow, including delays between requests and ensuring resilient fetching. + + +**Related Classes/Methods**: + +- `StreamProcessor`:1-1000 + + +### StreamUniquenessManager +Maintains a limited set of recently seen items to ensure uniqueness within a data stream. This prevents reprocessing of duplicate items, which is crucial for real-time data consumption. + + +**Related Classes/Methods**: + +- `StreamUniquenessManager`:1-1000 + + +### StreamBackoffHandler +Implements an exponential backoff strategy to manage delays between stream requests. This is critical for respecting API rate limits and preventing excessive requests that could lead to temporary bans. + + +**Related Classes/Methods**: + +- `StreamBackoffHandler`:1-1000 + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) diff --git a/.codeboarding/Object_Transformation_Layer.json b/.codeboarding/Object_Transformation_Layer.json new file mode 100644 index 000000000..a82420ecd --- /dev/null +++ b/.codeboarding/Object_Transformation_Layer.json @@ -0,0 +1,92 @@ +{ + "description": "The `praw.objector` subsystem is designed to seamlessly convert raw data from the Reddit API into usable PRAW objects while providing robust error handling. The `Objector` class serves as the central entry point, orchestrating the objectification and error-checking processes. The `objectify` method, with the assistance of `_objectify_dict`, recursively transforms complex data structures into their corresponding PRAW object representations. Concurrently, the `check_error` method, by delegating to `parse_error`, ensures that any API-reported errors are properly identified and converted into structured exceptions, maintaining the integrity and reliability of the data processing pipeline. This clear separation of concerns between data transformation and error management allows for a modular and maintainable architecture.", + "components": [ + { + "name": "praw.objector.Objector", + "description": "The central orchestrator of the transformation process, converting raw JSON responses into structured Python objects and managing error detection. It acts as the primary interface for the objectification process.", + "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 + } + ], + "can_expand": true + }, + { + "name": "praw.objector.Objector:objectify", + "description": "Implements the core recursive logic for data transformation, traversing raw JSON data, identifying appropriate PRAW object types, and instantiating them. This method is the heart of the data mapping functionality.", + "referenced_source_code": [ + { + "qualified_name": "praw.objector.Objector:objectify", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py", + "reference_start_line": 199, + "reference_end_line": 279 + } + ], + "can_expand": true + }, + { + "name": "praw.objector.Objector:_objectify_dict", + "description": "A specialized helper method for `objectify`, focusing on converting individual dictionary elements within the raw data into their corresponding PRAW object representations. It handles the granular conversion of data structures.", + "referenced_source_code": [ + { + "qualified_name": "praw.objector.Objector:_objectify_dict", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py", + "reference_start_line": 46, + "reference_end_line": 197 + } + ], + "can_expand": false + }, + { + "name": "praw.objector.Objector:check_error", + "description": "Responsible for scanning API responses for error indicators and delegating to `parse_error` if an error is detected. This ensures robust error handling within the transformation pipeline.", + "referenced_source_code": [ + { + "qualified_name": "praw.objector.Objector:check_error", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py", + "reference_start_line": 6, + "reference_end_line": 11 + } + ], + "can_expand": false + }, + { + "name": "praw.objector.Objector:parse_error", + "description": "Interprets raw error data from the API response, converting it into a structured format or raising a specific exception relevant to the PRAW library. This component standardizes error reporting.", + "referenced_source_code": [ + { + "qualified_name": "praw.objector.Objector:parse_error", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py", + "reference_start_line": 13, + "reference_end_line": 44 + } + ], + "can_expand": false + } + ], + "components_relations": [ + { + "relation": "invokes", + "src_name": "praw.objector.Objector", + "dst_name": "praw.objector.Objector:objectify" + }, + { + "relation": "invokes", + "src_name": "praw.objector.Objector", + "dst_name": "praw.objector.Objector:check_error" + }, + { + "relation": "utilizes", + "src_name": "praw.objector.Objector:objectify", + "dst_name": "praw.objector.Objector:_objectify_dict" + }, + { + "relation": "delegates to", + "src_name": "praw.objector.Objector:check_error", + "dst_name": "praw.objector.Objector:parse_error" + } + ] +} diff --git a/.codeboarding/Object_Transformation_Layer.md b/.codeboarding/Object_Transformation_Layer.md new file mode 100644 index 000000000..92308c366 --- /dev/null +++ b/.codeboarding/Object_Transformation_Layer.md @@ -0,0 +1,67 @@ +```mermaid +graph LR + praw_objector_Objector["praw.objector.Objector"] + praw_objector_Objector_objectify["praw.objector.Objector:objectify"] + praw_objector_Objector__objectify_dict["praw.objector.Objector:_objectify_dict"] + praw_objector_Objector_check_error["praw.objector.Objector:check_error"] + praw_objector_Objector_parse_error["praw.objector.Objector:parse_error"] + praw_objector_Objector -- "invokes" --> praw_objector_Objector_objectify + praw_objector_Objector -- "invokes" --> praw_objector_Objector_check_error + praw_objector_Objector_objectify -- "utilizes" --> praw_objector_Objector__objectify_dict + praw_objector_Objector_check_error -- "delegates to" --> praw_objector_Objector_parse_error +``` + +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Details + +The `praw.objector` subsystem is designed to seamlessly convert raw data from the Reddit API into usable PRAW objects while providing robust error handling. The `Objector` class serves as the central entry point, orchestrating the objectification and error-checking processes. The `objectify` method, with the assistance of `_objectify_dict`, recursively transforms complex data structures into their corresponding PRAW object representations. Concurrently, the `check_error` method, by delegating to `parse_error`, ensures that any API-reported errors are properly identified and converted into structured exceptions, maintaining the integrity and reliability of the data processing pipeline. This clear separation of concerns between data transformation and error management allows for a modular and maintainable architecture. + +### praw.objector.Objector +The central orchestrator of the transformation process, converting raw JSON responses into structured Python objects and managing error detection. It acts as the primary interface for the objectification process. + + +**Related Classes/Methods**: + +- `praw.objector.Objector`:17-263 + + +### praw.objector.Objector:objectify +Implements the core recursive logic for data transformation, traversing raw JSON data, identifying appropriate PRAW object types, and instantiating them. This method is the heart of the data mapping functionality. + + +**Related Classes/Methods**: + +- `praw.objector.Objector:objectify`:199-279 + + +### praw.objector.Objector:_objectify_dict +A specialized helper method for `objectify`, focusing on converting individual dictionary elements within the raw data into their corresponding PRAW object representations. It handles the granular conversion of data structures. + + +**Related Classes/Methods**: + +- `praw.objector.Objector:_objectify_dict`:46-197 + + +### praw.objector.Objector:check_error +Responsible for scanning API responses for error indicators and delegating to `parse_error` if an error is detected. This ensures robust error handling within the transformation pipeline. + + +**Related Classes/Methods**: + +- `praw.objector.Objector:check_error`:6-11 + + +### praw.objector.Objector:parse_error +Interprets raw error data from the API response, converting it into a structured format or raising a specific exception relevant to the PRAW library. This component standardizes error reporting. + + +**Related Classes/Methods**: + +- `praw.objector.Objector:parse_error`:13-44 + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) diff --git a/.codeboarding/Reddit_Data_Models.json b/.codeboarding/Reddit_Data_Models.json new file mode 100644 index 000000000..a449a84f7 --- /dev/null +++ b/.codeboarding/Reddit_Data_Models.json @@ -0,0 +1,146 @@ +{ + "description": "The PRAW library's core architecture for interacting with Reddit content is centered around key models representing Reddit entities. The Subreddit component acts as a central hub for community-specific interactions, enabling the creation and retrieval of Submission objects. Submission objects, in turn, manage post data and facilitate interactions with Comment threads. Both Submission and Comment leverage the VotableMixin for consistent voting functionality, demonstrating effective code reuse through inheritance. User-centric operations are handled by the Redditor component, which is involved in Modmail conversations. Modmail itself is composed by Subreddit, indicating its role in community moderation. LiveThread and WikiPage represent distinct content streams and informational pages, with WikiPage being directly associated with a Subreddit. This design emphasizes a clear separation of concerns, with each component encapsulating specific Reddit functionality and interacting through well-defined relationships to manage and present Reddit data.", + "components": [ + { + "name": "Subreddit", + "description": "Manages subreddit data, submissions, moderation, flair, and style. It acts as a primary facade for subreddit-specific API calls, allowing users to interact with a community's content and settings.", + "referenced_source_code": [ + { + "qualified_name": "praw.models.reddit.subreddit.Subreddit", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/subreddit.py", + "reference_start_line": 2446, + "reference_end_line": 2446 + } + ], + "can_expand": true + }, + { + "name": "Submission", + "description": "Encapsulates Reddit post data, including content, flair, and moderation status. It provides methods for retrieving content and interacting with the post (e.g., voting, commenting).", + "referenced_source_code": [ + { + "qualified_name": "praw.models.reddit.submission.Submission", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/submission.py", + "reference_start_line": 716, + "reference_end_line": 716 + } + ], + "can_expand": true + }, + { + "name": "Comment", + "description": "Manages individual comment data, including its content, author, and hierarchical position within a discussion. It provides methods for moderation and navigating comment threads.", + "referenced_source_code": [ + { + "qualified_name": "Comment", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 582, + "reference_end_line": 596 + } + ], + "can_expand": false + }, + { + "name": "Redditor", + "description": "Provides access to user-specific information, including profile details, submitted content, and comments. It enables interactions related to a specific Reddit user.", + "referenced_source_code": [ + { + "qualified_name": "Redditor", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 810, + "reference_end_line": 819 + } + ], + "can_expand": true + }, + { + "name": "VotableMixin", + "description": "A mixin class that provides common voting functionality (upvote, downvote, clear vote) to any Reddit entity that can be voted on. This promotes code reuse and consistency across votable models.", + "referenced_source_code": [ + { + "qualified_name": "VotableMixin", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/votable.py", + "reference_start_line": 8, + "reference_end_line": 92 + } + ], + "can_expand": false + }, + { + "name": "Modmail", + "description": "Represents a modmail conversation, facilitating communication between moderators and users, or between moderators themselves. It encapsulates messages and conversation states.", + "referenced_source_code": [ + { + "qualified_name": "Modmail", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/subreddit.py", + "reference_start_line": 2627, + "reference_end_line": 2639 + } + ], + "can_expand": true + }, + { + "name": "LiveThread", + "description": "Manages data and interactions for Reddit Live Threads, which are real-time, event-driven content streams. It provides access to updates and thread metadata.", + "referenced_source_code": [ + { + "qualified_name": "LiveThread", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/live.py", + "reference_start_line": 261, + "reference_end_line": 471 + } + ], + "can_expand": true + }, + { + "name": "WikiPage", + "description": "Abstracts the content and moderation aspects of a Reddit Wiki Page. It allows for retrieval, editing, and management of wiki content within a subreddit.", + "referenced_source_code": [ + { + "qualified_name": "WikiPage", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/wikipage.py", + "reference_start_line": 146, + "reference_end_line": 314 + } + ], + "can_expand": false + } + ], + "components_relations": [ + { + "relation": "creates and fetches", + "src_name": "Subreddit", + "dst_name": "Submission" + }, + { + "relation": "composes", + "src_name": "Subreddit", + "dst_name": "Modmail" + }, + { + "relation": "retrieves and references", + "src_name": "Submission", + "dst_name": "Comment" + }, + { + "relation": "inherits from", + "src_name": "Submission", + "dst_name": "VotableMixin" + }, + { + "relation": "inherits from", + "src_name": "Comment", + "dst_name": "VotableMixin" + }, + { + "relation": "involves", + "src_name": "Modmail", + "dst_name": "Redditor" + }, + { + "relation": "associated with", + "src_name": "WikiPage", + "dst_name": "Subreddit" + } + ] +} diff --git a/.codeboarding/Reddit_Data_Models.md b/.codeboarding/Reddit_Data_Models.md new file mode 100644 index 000000000..6ff2267f5 --- /dev/null +++ b/.codeboarding/Reddit_Data_Models.md @@ -0,0 +1,100 @@ +```mermaid +graph LR + Subreddit["Subreddit"] + Submission["Submission"] + Comment["Comment"] + Redditor["Redditor"] + VotableMixin["VotableMixin"] + Modmail["Modmail"] + LiveThread["LiveThread"] + WikiPage["WikiPage"] + Subreddit -- "creates and fetches" --> Submission + Subreddit -- "composes" --> Modmail + Submission -- "retrieves and references" --> Comment + Submission -- "inherits from" --> VotableMixin + Comment -- "inherits from" --> VotableMixin + Modmail -- "involves" --> Redditor + WikiPage -- "associated with" --> Subreddit +``` + +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Details + +The PRAW library's core architecture for interacting with Reddit content is centered around key models representing Reddit entities. The Subreddit component acts as a central hub for community-specific interactions, enabling the creation and retrieval of Submission objects. Submission objects, in turn, manage post data and facilitate interactions with Comment threads. Both Submission and Comment leverage the VotableMixin for consistent voting functionality, demonstrating effective code reuse through inheritance. User-centric operations are handled by the Redditor component, which is involved in Modmail conversations. Modmail itself is composed by Subreddit, indicating its role in community moderation. LiveThread and WikiPage represent distinct content streams and informational pages, with WikiPage being directly associated with a Subreddit. This design emphasizes a clear separation of concerns, with each component encapsulating specific Reddit functionality and interacting through well-defined relationships to manage and present Reddit data. + +### Subreddit +Manages subreddit data, submissions, moderation, flair, and style. It acts as a primary facade for subreddit-specific API calls, allowing users to interact with a community's content and settings. + + +**Related Classes/Methods**: + +- `praw.models.reddit.subreddit.Subreddit` + + +### Submission +Encapsulates Reddit post data, including content, flair, and moderation status. It provides methods for retrieving content and interacting with the post (e.g., voting, commenting). + + +**Related Classes/Methods**: + +- `praw.models.reddit.submission.Submission` + + +### Comment +Manages individual comment data, including its content, author, and hierarchical position within a discussion. It provides methods for moderation and navigating comment threads. + + +**Related Classes/Methods**: + +- `Comment`:582-596 + + +### Redditor +Provides access to user-specific information, including profile details, submitted content, and comments. It enables interactions related to a specific Reddit user. + + +**Related Classes/Methods**: + +- `Redditor`:810-819 + + +### VotableMixin +A mixin class that provides common voting functionality (upvote, downvote, clear vote) to any Reddit entity that can be voted on. This promotes code reuse and consistency across votable models. + + +**Related Classes/Methods**: + +- `VotableMixin`:8-92 + + +### Modmail +Represents a modmail conversation, facilitating communication between moderators and users, or between moderators themselves. It encapsulates messages and conversation states. + + +**Related Classes/Methods**: + +- `Modmail`:2627-2639 + + +### LiveThread +Manages data and interactions for Reddit Live Threads, which are real-time, event-driven content streams. It provides access to updates and thread metadata. + + +**Related Classes/Methods**: + +- `LiveThread`:261-471 + + +### WikiPage +Abstracts the content and moderation aspects of a Reddit Wiki Page. It allows for retrieval, editing, and management of wiki content within a subreddit. + + +**Related Classes/Methods**: + +- `WikiPage`:146-314 + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) diff --git a/.codeboarding/analysis.json b/.codeboarding/analysis.json new file mode 100644 index 000000000..48c04209f --- /dev/null +++ b/.codeboarding/analysis.json @@ -0,0 +1,211 @@ +{ + "description": "The PRAW architecture is designed as a robust API wrapper, providing an object-oriented interface to the Reddit API. It centers around the `API Client Core`, which orchestrates all network interactions, leveraging the `Configuration Manager` for settings and delegating raw response processing to the `Object Transformation Layer`. This layer is responsible for mapping raw API data into rich `Reddit Data Models`, which encapsulate Reddit entities and their behaviors. For handling collections and real-time data, the `Listing & Stream Processors` work in conjunction with the `API Client Core` and `Reddit Data Models`. Critical to its reliability, the `Exception Handling` component provides structured error reporting across the system. This design ensures a clear separation of concerns, facilitating maintainability, extensibility, and a developer-friendly experience, making it ideal for both documentation and visual flow graph representation.", + "components": [ + { + "name": "API Client Core", + "description": "The central orchestrator for all interactions with the Reddit API, managing HTTP requests, authentication, and rate limiting.", + "referenced_source_code": [ + { + "qualified_name": "praw.reddit.Reddit.__init__", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 1, + "reference_end_line": 1 + }, + { + "qualified_name": "praw.reddit.Reddit.request", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 1, + "reference_end_line": 1 + }, + { + "qualified_name": "praw.reddit.Reddit._objectify_request", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 1, + "reference_end_line": 1 + }, + { + "qualified_name": "praw.reddit.Reddit._handle_rate_limit", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 1, + "reference_end_line": 1 + } + ], + "can_expand": true + }, + { + "name": "Configuration Manager", + "description": "Handles the loading, storage, and provision of PRAW's operational settings, including API credentials and user agent strings.", + "referenced_source_code": [ + { + "qualified_name": "praw.config.Config.__init__", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/config.py", + "reference_start_line": 1, + "reference_end_line": 1 + }, + { + "qualified_name": "praw.config.Config._load_config", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/config.py", + "reference_start_line": 1, + "reference_end_line": 1 + } + ], + "can_expand": false + }, + { + "name": "Object Transformation Layer", + "description": "Acts as a data mapper, converting raw JSON responses from the Reddit API into rich, object-oriented Python representations (`Reddit Data Models`).", + "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 + }, + { + "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 + } + ], + "can_expand": true + }, + { + "name": "Reddit Data Models", + "description": "A comprehensive set of classes representing various Reddit entities (e.g., `Subreddit`, `Submission`, `Comment`, `Redditor`). These models encapsulate data and provide high-level methods for interacting with their respective API endpoints.", + "referenced_source_code": [ + { + "qualified_name": "praw.models.reddit.subreddit.Subreddit.submit", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/subreddit.py", + "reference_start_line": 1, + "reference_end_line": 1 + }, + { + "qualified_name": "praw.models.reddit.submission.Submission._fetch_data", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/submission.py", + "reference_start_line": 1, + "reference_end_line": 1 + }, + { + "qualified_name": "praw.models.reddit.comment.Comment.parent", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/comment.py", + "reference_start_line": 1, + "reference_end_line": 1 + }, + { + "qualified_name": "praw.models.reddit.redditor.Redditor._fetch_info", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/redditor.py", + "reference_start_line": 1, + "reference_end_line": 1 + }, + { + "qualified_name": "praw.models.reddit.mixins.votable.VotableMixin._vote", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/votable.py", + "reference_start_line": 1, + "reference_end_line": 1 + } + ], + "can_expand": true + }, + { + "name": "Listing & Stream Processors", + "description": "Provides mechanisms for iterating through paginated API responses (listings) and consuming real-time data streams from Reddit, handling pagination logic and item uniqueness.", + "referenced_source_code": [ + { + "qualified_name": "praw.models.listing.generator.ListingGenerator.__next__", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py", + "reference_start_line": 1, + "reference_end_line": 1 + }, + { + "qualified_name": "praw.models.listing.generator.ListingGenerator._next_batch", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py", + "reference_start_line": 1, + "reference_end_line": 1 + } + ], + "can_expand": true + }, + { + "name": "Exception Handling", + "description": "Defines a hierarchy of custom exception classes specific to PRAW and provides utilities to translate raw API error messages into structured exceptions.", + "referenced_source_code": [ + { + "qualified_name": "praw.exceptions.PRAWException", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py", + "reference_start_line": 14, + "reference_end_line": 15 + }, + { + "qualified_name": "praw.exceptions.parse_exception_list", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py", + "reference_start_line": 173, + "reference_end_line": 189 + } + ], + "can_expand": true + } + ], + "components_relations": [ + { + "relation": "uses", + "src_name": "API Client Core", + "dst_name": "Configuration Manager" + }, + { + "relation": "sends raw responses to", + "src_name": "API Client Core", + "dst_name": "Object Transformation Layer" + }, + { + "relation": "reports errors to", + "src_name": "API Client Core", + "dst_name": "Exception Handling" + }, + { + "relation": "receives raw responses from", + "src_name": "Object Transformation Layer", + "dst_name": "API Client Core" + }, + { + "relation": "instantiates", + "src_name": "Object Transformation Layer", + "dst_name": "Reddit Data Models" + }, + { + "relation": "parses errors with", + "src_name": "Object Transformation Layer", + "dst_name": "Exception Handling" + }, + { + "relation": "initiates requests via", + "src_name": "Reddit Data Models", + "dst_name": "API Client Core" + }, + { + "relation": "are utilized by", + "src_name": "Reddit Data Models", + "dst_name": "Listing & Stream Processors" + }, + { + "relation": "fetches batches via", + "src_name": "Listing & Stream Processors", + "dst_name": "API Client Core" + }, + { + "relation": "utilizes", + "src_name": "Listing & Stream Processors", + "dst_name": "Reddit Data Models" + }, + { + "relation": "receives errors from", + "src_name": "Exception Handling", + "dst_name": "API Client Core" + }, + { + "relation": "receives parsed errors from", + "src_name": "Exception Handling", + "dst_name": "Object Transformation Layer" + } + ] +} diff --git a/.codeboarding/codeboarding_version.json b/.codeboarding/codeboarding_version.json new file mode 100644 index 000000000..c309e60c7 --- /dev/null +++ b/.codeboarding/codeboarding_version.json @@ -0,0 +1,4 @@ +{ + "commit_hash": "f2a2e7884e4c4cd77887970471d090bd0da12349", + "code_boarding_version": "0.1.0" +} diff --git a/.codeboarding/on_boarding.md b/.codeboarding/on_boarding.md new file mode 100644 index 000000000..c71e4e9cc --- /dev/null +++ b/.codeboarding/on_boarding.md @@ -0,0 +1,101 @@ +```mermaid +graph LR + API_Client_Core["API Client Core"] + Configuration_Manager["Configuration Manager"] + Object_Transformation_Layer["Object Transformation Layer"] + Reddit_Data_Models["Reddit Data Models"] + Listing_Stream_Processors["Listing & Stream Processors"] + Exception_Handling["Exception Handling"] + API_Client_Core -- "uses" --> Configuration_Manager + API_Client_Core -- "sends raw responses to" --> Object_Transformation_Layer + API_Client_Core -- "reports errors to" --> Exception_Handling + Object_Transformation_Layer -- "receives raw responses from" --> API_Client_Core + Object_Transformation_Layer -- "instantiates" --> Reddit_Data_Models + Object_Transformation_Layer -- "parses errors with" --> Exception_Handling + Reddit_Data_Models -- "initiates requests via" --> API_Client_Core + Reddit_Data_Models -- "are utilized by" --> Listing_Stream_Processors + Listing_Stream_Processors -- "fetches batches via" --> API_Client_Core + Listing_Stream_Processors -- "utilizes" --> Reddit_Data_Models + Exception_Handling -- "receives errors from" --> API_Client_Core + Exception_Handling -- "receives parsed errors from" --> Object_Transformation_Layer + click API_Client_Core href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/API_Client_Core.md" "Details" + click Object_Transformation_Layer href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Object_Transformation_Layer.md" "Details" + click Reddit_Data_Models href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Reddit_Data_Models.md" "Details" + click Listing_Stream_Processors href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Listing_Stream_Processors.md" "Details" + click Exception_Handling href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Exception_Handling.md" "Details" +``` + +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Details + +The PRAW architecture is designed as a robust API wrapper, providing an object-oriented interface to the Reddit API. It centers around the `API Client Core`, which orchestrates all network interactions, leveraging the `Configuration Manager` for settings and delegating raw response processing to the `Object Transformation Layer`. This layer is responsible for mapping raw API data into rich `Reddit Data Models`, which encapsulate Reddit entities and their behaviors. For handling collections and real-time data, the `Listing & Stream Processors` work in conjunction with the `API Client Core` and `Reddit Data Models`. Critical to its reliability, the `Exception Handling` component provides structured error reporting across the system. This design ensures a clear separation of concerns, facilitating maintainability, extensibility, and a developer-friendly experience, making it ideal for both documentation and visual flow graph representation. + +### API Client Core [[Expand]](./API_Client_Core.md) +The central orchestrator for all interactions with the Reddit API, managing HTTP requests, authentication, and rate limiting. + + +**Related Classes/Methods**: + +- `praw.reddit.Reddit.__init__` +- `praw.reddit.Reddit.request` +- `praw.reddit.Reddit._objectify_request` +- `praw.reddit.Reddit._handle_rate_limit` + + +### Configuration Manager +Handles the loading, storage, and provision of PRAW's operational settings, including API credentials and user agent strings. + + +**Related Classes/Methods**: + +- `praw.config.Config.__init__` +- `praw.config.Config._load_config` + + +### Object Transformation Layer [[Expand]](./Object_Transformation_Layer.md) +Acts as a data mapper, converting raw JSON responses from the Reddit API into rich, object-oriented Python representations (`Reddit Data Models`). + + +**Related Classes/Methods**: + +- `praw.objector.Objector.objectify` +- `praw.objector.Objector.check_error` + + +### Reddit Data Models [[Expand]](./Reddit_Data_Models.md) +A comprehensive set of classes representing various Reddit entities (e.g., `Subreddit`, `Submission`, `Comment`, `Redditor`). These models encapsulate data and provide high-level methods for interacting with their respective API endpoints. + + +**Related Classes/Methods**: + +- `praw.models.reddit.subreddit.Subreddit.submit` +- `praw.models.reddit.submission.Submission._fetch_data` +- `praw.models.reddit.comment.Comment.parent` +- `praw.models.reddit.redditor.Redditor._fetch_info` +- `praw.models.reddit.mixins.votable.VotableMixin._vote` + + +### Listing & Stream Processors [[Expand]](./Listing_Stream_Processors.md) +Provides mechanisms for iterating through paginated API responses (listings) and consuming real-time data streams from Reddit, handling pagination logic and item uniqueness. + + +**Related Classes/Methods**: + +- `praw.models.listing.generator.ListingGenerator.__next__` +- `praw.models.listing.generator.ListingGenerator._next_batch` + + +### Exception Handling [[Expand]](./Exception_Handling.md) +Defines a hierarchy of custom exception classes specific to PRAW and provides utilities to translate raw API error messages into structured exceptions. + + +**Related Classes/Methods**: + +- `praw.exceptions.PRAWException`:14-15 +- `praw.exceptions.parse_exception_list`:173-189 + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) From 3acb442f380f1d496c53de659f5f1a03b633f325 Mon Sep 17 00:00:00 2001 From: ivanmilevtues Date: Mon, 1 Sep 2025 19:31:59 +0200 Subject: [PATCH 05/23] Change default to .rst --- .github/workflows/docs_codeboarding.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/docs_codeboarding.yml b/.github/workflows/docs_codeboarding.yml index 11262b34a..0e94a301e 100644 --- a/.github/workflows/docs_codeboarding.yml +++ b/.github/workflows/docs_codeboarding.yml @@ -28,12 +28,12 @@ on: output_format: description: 'Output format for documentation' required: false - default: '.md' + default: '.rst' type: choice options: + - '.rst' - '.md' - '.mdx' - - '.rst' push: branches: - master @@ -77,7 +77,7 @@ jobs: 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 || '.md' }} + output_format: ${{ github.event.inputs.output_format || '.rst' }} - name: Display Action Results run: | @@ -113,7 +113,7 @@ jobs: - 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 || '.md' }} + - 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 }} From 5dcaebd92e024603905c0d8a277ff5568fb44eee Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Mon, 1 Sep 2025 17:33:49 +0000 Subject: [PATCH 06/23] docs: update codeboarding documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 📚 Documentation Update This commit contains updated documentation files fetched from the CodeBoarding service. ### 📊 Summary - Documentation files created/updated: 5 - JSON files created/updated: 6 - Documentation directory: .codeboarding/ - JSON directory: .codeboarding/ - Output format: .rst - Repository analyzed: https://github.com/CodeBoarding/praw - Source branch: main - Target branch: main 🤖 This commit was automatically generated by the CodeBoarding documentation update workflow. --- .codeboarding/API_Client_Core.json | 21 +-- .codeboarding/API_Client_Core.md | 100 --------------- .codeboarding/API_Client_Core.rst | 115 +++++++++++++++++ .codeboarding/Exception_Handling.json | 98 -------------- .codeboarding/Exception_Handling.md | 68 ---------- .codeboarding/Listing_Stream_Processors.json | 21 +-- .codeboarding/Listing_Stream_Processors.md | 92 ------------- .codeboarding/Listing_Stream_Processors.rst | 105 +++++++++++++++ .../Object_Transformation_Layer.json | 15 +-- .codeboarding/Object_Transformation_Layer.md | 67 ---------- .codeboarding/Object_Transformation_Layer.rst | 80 ++++++++++++ .codeboarding/Reddit_Data_Models.json | 24 ++-- .codeboarding/Reddit_Data_Models.md | 100 --------------- .codeboarding/Reddit_Data_Models.rst | 113 ++++++++++++++++ .codeboarding/analysis.json | 2 +- .codeboarding/codeboarding_version.json | 2 +- .codeboarding/on_boarding.md | 101 --------------- .codeboarding/on_boarding.rst | 121 ++++++++++++++++++ 18 files changed, 563 insertions(+), 682 deletions(-) delete mode 100644 .codeboarding/API_Client_Core.md create mode 100644 .codeboarding/API_Client_Core.rst delete mode 100644 .codeboarding/Exception_Handling.json delete mode 100644 .codeboarding/Exception_Handling.md delete mode 100644 .codeboarding/Listing_Stream_Processors.md create mode 100644 .codeboarding/Listing_Stream_Processors.rst delete mode 100644 .codeboarding/Object_Transformation_Layer.md create mode 100644 .codeboarding/Object_Transformation_Layer.rst delete mode 100644 .codeboarding/Reddit_Data_Models.md create mode 100644 .codeboarding/Reddit_Data_Models.rst delete mode 100644 .codeboarding/on_boarding.md create mode 100644 .codeboarding/on_boarding.rst diff --git a/.codeboarding/API_Client_Core.json b/.codeboarding/API_Client_Core.json index 5c1fbdbad..33eab5c8a 100644 --- a/.codeboarding/API_Client_Core.json +++ b/.codeboarding/API_Client_Core.json @@ -11,8 +11,7 @@ "reference_start_line": 57, "reference_end_line": 901 } - ], - "can_expand": true + ] }, { "name": "Client Initializer", @@ -36,8 +35,7 @@ "reference_start_line": 479, "reference_end_line": 525 } - ], - "can_expand": true + ] }, { "name": "Request Executor", @@ -49,8 +47,7 @@ "reference_start_line": 0, "reference_end_line": 0 } - ], - "can_expand": false + ] }, { "name": "Response Objectifier", @@ -62,8 +59,7 @@ "reference_start_line": 0, "reference_end_line": 0 } - ], - "can_expand": true + ] }, { "name": "Rate Limit Manager", @@ -75,8 +71,7 @@ "reference_start_line": 0, "reference_end_line": 0 } - ], - "can_expand": false + ] }, { "name": "API Operation Methods", @@ -112,8 +107,7 @@ "reference_start_line": 0, "reference_end_line": 0 } - ], - "can_expand": true + ] }, { "name": "Async Checker", @@ -125,8 +119,7 @@ "reference_start_line": 388, "reference_end_line": 411 } - ], - "can_expand": false + ] } ], "components_relations": [ diff --git a/.codeboarding/API_Client_Core.md b/.codeboarding/API_Client_Core.md deleted file mode 100644 index 418e5ec0f..000000000 --- a/.codeboarding/API_Client_Core.md +++ /dev/null @@ -1,100 +0,0 @@ -```mermaid -graph LR - API_Client_Core["API Client Core"] - Client_Initializer["Client Initializer"] - Request_Executor["Request Executor"] - Response_Objectifier["Response Objectifier"] - Rate_Limit_Manager["Rate Limit Manager"] - API_Operation_Methods["API Operation Methods"] - Async_Checker["Async Checker"] - Client_Initializer -- "initializes" --> API_Client_Core - API_Client_Core -- "manages" --> Request_Executor - API_Client_Core -- "manages" --> Response_Objectifier - API_Client_Core -- "manages" --> Rate_Limit_Manager - API_Client_Core -- "exposes" --> API_Operation_Methods - API_Operation_Methods -- "invokes" --> Request_Executor - Request_Executor -- "checks" --> Async_Checker - Request_Executor -- "returns raw response to" --> Response_Objectifier - Response_Objectifier -- "transforms for" --> API_Operation_Methods - API_Operation_Methods -- "consults" --> Rate_Limit_Manager - click API_Client_Core href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/API_Client_Core.md" "Details" -``` - -[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) - -## Details - -The PRAW Reddit API client is structured around the `API Client Core`, which serves as the primary interface for users. This core is set up by the `Client Initializer`, configuring essential components like the HTTP client and response parsing. User interactions, such as fetching data or creating posts, are handled by `API Operation Methods`. These methods delegate the actual HTTP communication to the `Request Executor`, which may consult the `Async Checker` for proper asynchronous execution. Upon receiving a raw response, the `Request Executor` passes it to the `Response Objectifier` for transformation into structured Python objects, which are then returned to the `API Operation Methods`. Throughout this process, the `Rate Limit Manager` is consulted to ensure adherence to Reddit's API usage policies, with the `API Client Core` overseeing and managing these interactions. - -### API Client Core [[Expand]](./API_Client_Core.md) -Serves as the main entry point for users to interact with the Reddit API. It orchestrates all underlying operations, manages the client's state, and exposes a high-level, object-oriented interface. - - -**Related Classes/Methods**: - -- `praw.reddit.Reddit`:57-901 - - -### Client Initializer -Sets up the API Client Core instance, including configuring the underlying HTTP client (prawcore) and the response objectification mechanism. It integrates `prawcore` for HTTP requests and the `Objector` for response parsing. - - -**Related Classes/Methods**: - -- `praw.reddit.Reddit.__init__` -- `praw.reddit._prepare_prawcore`:527-546 -- `praw.reddit._prepare_objector`:479-525 - - -### Request Executor -Executes the raw HTTP requests to the Reddit API, handling the low-level communication details. - - -**Related Classes/Methods**: - -- `praw.reddit.Reddit.request` - - -### Response Objectifier -Transforms the raw JSON responses from the API into structured PRAW Python objects, making them easier to consume and work with. - - -**Related Classes/Methods**: - -- `praw.reddit.Reddit._objectify_request` - - -### Rate Limit Manager -Monitors and enforces Reddit's API rate limits, pausing requests when necessary to prevent exceeding usage quotas and ensuring compliance. - - -**Related Classes/Methods**: - -- `praw.reddit.Reddit._handle_rate_limit` - - -### API Operation Methods -Provide specific, high-level methods for common API operations (e.g., fetching data, creating posts, deleting resources), abstracting the underlying request and response handling details from the end-user. - - -**Related Classes/Methods**: - -- `praw.reddit.Reddit.get` -- `praw.reddit.Reddit.post` -- `praw.reddit.Reddit.delete` -- `praw.reddit.Reddit.patch` -- `praw.reddit.Reddit.put` - - -### Async Checker -Manages and verifies the asynchronous context for operations, ensuring proper execution in async environments. - - -**Related Classes/Methods**: - -- `praw.reddit._check_for_async`:388-411 - - - - -### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) diff --git a/.codeboarding/API_Client_Core.rst b/.codeboarding/API_Client_Core.rst new file mode 100644 index 000000000..785f79d72 --- /dev/null +++ b/.codeboarding/API_Client_Core.rst @@ -0,0 +1,115 @@ +High-level diagram representation of: praw +========================================== + +.. mermaid:: + + graph LR + API_Client_Core["API Client Core"] + Client_Initializer["Client Initializer"] + Request_Executor["Request Executor"] + Response_Objectifier["Response Objectifier"] + Rate_Limit_Manager["Rate Limit Manager"] + API_Operation_Methods["API Operation Methods"] + Async_Checker["Async Checker"] + Client_Initializer -- "initializes" --> API_Client_Core + API_Client_Core -- "manages" --> Request_Executor + API_Client_Core -- "manages" --> Response_Objectifier + API_Client_Core -- "manages" --> Rate_Limit_Manager + API_Client_Core -- "exposes" --> API_Operation_Methods + API_Operation_Methods -- "invokes" --> Request_Executor + Request_Executor -- "checks" --> Async_Checker + Request_Executor -- "returns raw response to" --> Response_Objectifier + Response_Objectifier -- "transforms for" --> API_Operation_Methods + API_Operation_Methods -- "consults" --> Rate_Limit_Manager + click API_Client_Core href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/API_Client_Core.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/GeneratedOnBoardings +.. |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 Reddit API client is structured around the `API Client Core`, which serves as the primary interface for users. This core is set up by the `Client Initializer`, configuring essential components like the HTTP client and response parsing. User interactions, such as fetching data or creating posts, are handled by `API Operation Methods`. These methods delegate the actual HTTP communication to the `Request Executor`, which may consult the `Async Checker` for proper asynchronous execution. Upon receiving a raw response, the `Request Executor` passes it to the `Response Objectifier` for transformation into structured Python objects, which are then returned to the `API Operation Methods`. Throughout this process, the `Rate Limit Manager` is consulted to ensure adherence to Reddit's API usage policies, with the `API Client Core` overseeing and managing these interactions. + +API Client Core +^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +Serves as the main entry point for users to interact with the Reddit API. It orchestrates all underlying operations, manages the client's state, and exposes a high-level, object-oriented interface. + +**Related Classes/Methods**: + +* `QName:`praw.reddit.Reddit` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py`, Lines:(57:901) `_ + +Client Initializer +^^^^^^^^^^^^^^^^^^ + +Sets up the API Client Core instance, including configuring the underlying HTTP client (prawcore) and the response objectification mechanism. It integrates `prawcore` for HTTP requests and the `Objector` for response parsing. + +**Related Classes/Methods**: + +* `QName:`praw.reddit.Reddit.__init__` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` `_ +* `QName:`praw.reddit._prepare_prawcore` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py`, Lines:(527:546) `_ +* `QName:`praw.reddit._prepare_objector` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py`, Lines:(479:525) `_ + +Request Executor +^^^^^^^^^^^^^^^^ + +Executes the raw HTTP requests to the Reddit API, handling the low-level communication details. + +**Related Classes/Methods**: + +* `QName:`praw.reddit.Reddit.request` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` `_ + +Response Objectifier +^^^^^^^^^^^^^^^^^^^^ + +Transforms the raw JSON responses from the API into structured PRAW Python objects, making them easier to consume and work with. + +**Related Classes/Methods**: + +* `QName:`praw.reddit.Reddit._objectify_request` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` `_ + +Rate Limit Manager +^^^^^^^^^^^^^^^^^^ + +Monitors and enforces Reddit's API rate limits, pausing requests when necessary to prevent exceeding usage quotas and ensuring compliance. + +**Related Classes/Methods**: + +* `QName:`praw.reddit.Reddit._handle_rate_limit` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` `_ + +API Operation Methods +^^^^^^^^^^^^^^^^^^^^^ + +Provide specific, high-level methods for common API operations (e.g., fetching data, creating posts, deleting resources), abstracting the underlying request and response handling details from the end-user. + +**Related Classes/Methods**: + +* `QName:`praw.reddit.Reddit.get` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` `_ +* `QName:`praw.reddit.Reddit.post` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` `_ +* `QName:`praw.reddit.Reddit.delete` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` `_ +* `QName:`praw.reddit.Reddit.patch` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` `_ +* `QName:`praw.reddit.Reddit.put` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` `_ + +Async Checker +^^^^^^^^^^^^^ + +Manages and verifies the asynchronous context for operations, ensuring proper execution in async environments. + +**Related Classes/Methods**: + +* `QName:`praw.reddit._check_for_async` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py`, Lines:(388:411) `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/.codeboarding/Exception_Handling.json b/.codeboarding/Exception_Handling.json deleted file mode 100644 index 2c1ddc23d..000000000 --- a/.codeboarding/Exception_Handling.json +++ /dev/null @@ -1,98 +0,0 @@ -{ - "description": "The `Exception Handling` subsystem is encapsulated within the `praw.exceptions` module, primarily defined by the `praw/praw/exceptions.py` file. It provides a dedicated mechanism for handling and representing errors specific to the PRAW library and the Reddit API.", - "components": [ - { - "name": "PRAWException", - "description": "The foundational base class for all custom exceptions within the PRAW library. It ensures a consistent interface and common attributes for all PRAW-specific errors, acting as the root of the exception hierarchy.", - "referenced_source_code": [ - { - "qualified_name": "PRAWException", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py", - "reference_start_line": 14, - "reference_end_line": 15 - } - ], - "can_expand": false - }, - { - "name": "Specific PRAW Exception Classes", - "description": "A set of specialized exception classes (e.g., `APIException`, `ClientException`) that inherit from `PRAWException`. These classes represent distinct error conditions, such as those returned by the Reddit API or client-side operational failures, and encapsulate parsed error details for specific contexts.", - "referenced_source_code": [ - { - "qualified_name": "APIException", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py", - "reference_start_line": 170, - "reference_end_line": 201 - }, - { - "qualified_name": "ClientException", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py", - "reference_start_line": 74, - "reference_end_line": 75 - } - ], - "can_expand": false - }, - { - "name": "RedditErrorItem", - "description": "A lightweight data structure that encapsulates the details of a single error item. It stores parsed information such as the error message, associated field, and type, as extracted from raw API responses.", - "referenced_source_code": [ - { - "qualified_name": "RedditErrorItem", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py", - "reference_start_line": 18, - "reference_end_line": 71 - } - ], - "can_expand": false - }, - { - "name": "parse_exception_list", - "description": "A utility function responsible for processing raw error data, typically a list of error messages or codes received from Reddit API responses. It transforms this raw data into a structured collection of `RedditErrorItem` objects.", - "referenced_source_code": [ - { - "qualified_name": "parse_exception_list", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py", - "reference_start_line": 173, - "reference_end_line": 189 - } - ], - "can_expand": false - }, - { - "name": "error_message", - "description": "A utility function dedicated to formatting a list of `RedditErrorItem` objects into a concise and informative error string. This string is suitable for display to developers or for logging purposes.", - "referenced_source_code": [ - { - "qualified_name": "error_message", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py", - "reference_start_line": 21, - "reference_end_line": 29 - } - ], - "can_expand": false - } - ], - "components_relations": [ - { - "relation": "inherits from", - "src_name": "Specific PRAW Exception Classes", - "dst_name": "PRAWException" - }, - { - "relation": "invokes", - "src_name": "Specific PRAW Exception Classes", - "dst_name": "parse_exception_list" - }, - { - "relation": "calls", - "src_name": "Specific PRAW Exception Classes", - "dst_name": "error_message" - }, - { - "relation": "creates and returns", - "src_name": "parse_exception_list", - "dst_name": "RedditErrorItem" - } - ] -} diff --git a/.codeboarding/Exception_Handling.md b/.codeboarding/Exception_Handling.md deleted file mode 100644 index d531c0426..000000000 --- a/.codeboarding/Exception_Handling.md +++ /dev/null @@ -1,68 +0,0 @@ -```mermaid -graph LR - PRAWException["PRAWException"] - Specific_PRAW_Exception_Classes["Specific PRAW Exception Classes"] - RedditErrorItem["RedditErrorItem"] - parse_exception_list["parse_exception_list"] - error_message["error_message"] - Specific_PRAW_Exception_Classes -- "inherits from" --> PRAWException - Specific_PRAW_Exception_Classes -- "invokes" --> parse_exception_list - Specific_PRAW_Exception_Classes -- "calls" --> error_message - parse_exception_list -- "creates and returns" --> RedditErrorItem -``` - -[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) - -## Details - -The `Exception Handling` subsystem is encapsulated within the `praw.exceptions` module, primarily defined by the `praw/praw/exceptions.py` file. It provides a dedicated mechanism for handling and representing errors specific to the PRAW library and the Reddit API. - -### PRAWException -The foundational base class for all custom exceptions within the PRAW library. It ensures a consistent interface and common attributes for all PRAW-specific errors, acting as the root of the exception hierarchy. - - -**Related Classes/Methods**: - -- `PRAWException`:14-15 - - -### Specific PRAW Exception Classes -A set of specialized exception classes (e.g., `APIException`, `ClientException`) that inherit from `PRAWException`. These classes represent distinct error conditions, such as those returned by the Reddit API or client-side operational failures, and encapsulate parsed error details for specific contexts. - - -**Related Classes/Methods**: - -- `APIException`:170-201 -- `ClientException`:74-75 - - -### RedditErrorItem -A lightweight data structure that encapsulates the details of a single error item. It stores parsed information such as the error message, associated field, and type, as extracted from raw API responses. - - -**Related Classes/Methods**: - -- `RedditErrorItem`:18-71 - - -### parse_exception_list -A utility function responsible for processing raw error data, typically a list of error messages or codes received from Reddit API responses. It transforms this raw data into a structured collection of `RedditErrorItem` objects. - - -**Related Classes/Methods**: - -- `parse_exception_list`:173-189 - - -### error_message -A utility function dedicated to formatting a list of `RedditErrorItem` objects into a concise and informative error string. This string is suitable for display to developers or for logging purposes. - - -**Related Classes/Methods**: - -- `error_message`:21-29 - - - - -### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) diff --git a/.codeboarding/Listing_Stream_Processors.json b/.codeboarding/Listing_Stream_Processors.json index 9b3574709..880cc70bd 100644 --- a/.codeboarding/Listing_Stream_Processors.json +++ b/.codeboarding/Listing_Stream_Processors.json @@ -11,8 +11,7 @@ "reference_start_line": 17, "reference_end_line": 103 } - ], - "can_expand": false + ] }, { "name": "ListingBatchFetcher", @@ -24,8 +23,7 @@ "reference_start_line": 1, "reference_end_line": 1000 } - ], - "can_expand": true + ] }, { "name": "ListingDataExtractor", @@ -37,8 +35,7 @@ "reference_start_line": 1, "reference_end_line": 1000 } - ], - "can_expand": true + ] }, { "name": "ListingParameterMixin", @@ -50,8 +47,7 @@ "reference_start_line": 1, "reference_end_line": 1000 } - ], - "can_expand": false + ] }, { "name": "StreamProcessor", @@ -63,8 +59,7 @@ "reference_start_line": 1, "reference_end_line": 1000 } - ], - "can_expand": true + ] }, { "name": "StreamUniquenessManager", @@ -76,8 +71,7 @@ "reference_start_line": 1, "reference_end_line": 1000 } - ], - "can_expand": false + ] }, { "name": "StreamBackoffHandler", @@ -89,8 +83,7 @@ "reference_start_line": 1, "reference_end_line": 1000 } - ], - "can_expand": false + ] } ], "components_relations": [ diff --git a/.codeboarding/Listing_Stream_Processors.md b/.codeboarding/Listing_Stream_Processors.md deleted file mode 100644 index a266e5ddc..000000000 --- a/.codeboarding/Listing_Stream_Processors.md +++ /dev/null @@ -1,92 +0,0 @@ -```mermaid -graph LR - ListingGenerator["ListingGenerator"] - ListingBatchFetcher["ListingBatchFetcher"] - ListingDataExtractor["ListingDataExtractor"] - ListingParameterMixin["ListingParameterMixin"] - StreamProcessor["StreamProcessor"] - StreamUniquenessManager["StreamUniquenessManager"] - StreamBackoffHandler["StreamBackoffHandler"] - ListingGenerator -- "initiates data retrieval by calling" --> ListingBatchFetcher - ListingBatchFetcher -- "fetches data and returns it to" --> ListingGenerator - ListingBatchFetcher -- "invokes" --> ListingDataExtractor - ListingDataExtractor -- "provides the extracted list of items back to" --> ListingBatchFetcher - ListingParameterMixin -- "is utilized by" --> ListingBatchFetcher - StreamProcessor -- "utilizes" --> StreamUniquenessManager - StreamUniquenessManager -- "provides uniqueness checks for" --> StreamProcessor - StreamProcessor -- "consults" --> StreamBackoffHandler - StreamBackoffHandler -- "provides backoff durations to" --> StreamProcessor -``` - -[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) - -## Details - -This subsystem is responsible for abstracting the complexities of consuming data from the Reddit API, specifically handling paginated "listings" (e.g., posts in a subreddit) and continuous "streams" of new data (e.g., new comments). It ensures efficient data retrieval, manages pagination state, handles item uniqueness in streams, and implements robust backoff strategies to respect API rate limits. - -### ListingGenerator -Provides an iterable interface for consuming paginated API responses. It manages the state of pagination, such as the `_after` parameter, to fetch subsequent batches of data seamlessly. - - -**Related Classes/Methods**: - -- `ListingGenerator`:17-103 - - -### ListingBatchFetcher -Responsible for fetching a single batch of items from the Reddit API using the underlying `Reddit` client. It utilizes the pagination state provided by `ListingGenerator` to request the correct segment of data. - - -**Related Classes/Methods**: - -- `ListingBatchFetcher`:1-1000 - - -### ListingDataExtractor -Parses the raw JSON response received from the API, isolating and returning the actual list of data objects (e.g., posts, comments) from the API's wrapper structure. - - -**Related Classes/Methods**: - -- `ListingDataExtractor`:1-1000 - - -### ListingParameterMixin -Provides common methods for constructing API paths and parameters required for various types of listings. This ensures consistency and reusability across different listing endpoints. - - -**Related Classes/Methods**: - -- `ListingParameterMixin`:1-1000 - - -### StreamProcessor -Implements the foundational logic for consuming continuous data streams from the Reddit API. It manages the overall flow, including delays between requests and ensuring resilient fetching. - - -**Related Classes/Methods**: - -- `StreamProcessor`:1-1000 - - -### StreamUniquenessManager -Maintains a limited set of recently seen items to ensure uniqueness within a data stream. This prevents reprocessing of duplicate items, which is crucial for real-time data consumption. - - -**Related Classes/Methods**: - -- `StreamUniquenessManager`:1-1000 - - -### StreamBackoffHandler -Implements an exponential backoff strategy to manage delays between stream requests. This is critical for respecting API rate limits and preventing excessive requests that could lead to temporary bans. - - -**Related Classes/Methods**: - -- `StreamBackoffHandler`:1-1000 - - - - -### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) diff --git a/.codeboarding/Listing_Stream_Processors.rst b/.codeboarding/Listing_Stream_Processors.rst new file mode 100644 index 000000000..bdb692166 --- /dev/null +++ b/.codeboarding/Listing_Stream_Processors.rst @@ -0,0 +1,105 @@ +High-level diagram representation of: praw +========================================== + +.. mermaid:: + + graph LR + ListingGenerator["ListingGenerator"] + ListingBatchFetcher["ListingBatchFetcher"] + ListingDataExtractor["ListingDataExtractor"] + ListingParameterMixin["ListingParameterMixin"] + StreamProcessor["StreamProcessor"] + StreamUniquenessManager["StreamUniquenessManager"] + StreamBackoffHandler["StreamBackoffHandler"] + ListingGenerator -- "initiates data retrieval by calling" --> ListingBatchFetcher + ListingBatchFetcher -- "fetches data and returns it to" --> ListingGenerator + ListingBatchFetcher -- "invokes" --> ListingDataExtractor + ListingDataExtractor -- "provides the extracted list of items back to" --> ListingBatchFetcher + ListingParameterMixin -- "is utilized by" --> ListingBatchFetcher + StreamProcessor -- "utilizes" --> StreamUniquenessManager + StreamUniquenessManager -- "provides uniqueness checks for" --> StreamProcessor + StreamProcessor -- "consults" --> StreamBackoffHandler + StreamBackoffHandler -- "provides backoff durations to" --> StreamProcessor + +| |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/GeneratedOnBoardings +.. |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 +------- + +This subsystem is responsible for abstracting the complexities of consuming data from the Reddit API, specifically handling paginated "listings" (e.g., posts in a subreddit) and continuous "streams" of new data (e.g., new comments). It ensures efficient data retrieval, manages pagination state, handles item uniqueness in streams, and implements robust backoff strategies to respect API rate limits. + +ListingGenerator +^^^^^^^^^^^^^^^^ + +Provides an iterable interface for consuming paginated API responses. It manages the state of pagination, such as the `_after` parameter, to fetch subsequent batches of data seamlessly. + +**Related Classes/Methods**: + +* `QName:`ListingGenerator` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py`, Lines:(17:103) `_ + +ListingBatchFetcher +^^^^^^^^^^^^^^^^^^^ + +Responsible for fetching a single batch of items from the Reddit API using the underlying `Reddit` client. It utilizes the pagination state provided by `ListingGenerator` to request the correct segment of data. + +**Related Classes/Methods**: + +* `QName:`ListingBatchFetcher` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py`, Lines:(1:1000) `_ + +ListingDataExtractor +^^^^^^^^^^^^^^^^^^^^ + +Parses the raw JSON response received from the API, isolating and returning the actual list of data objects (e.g., posts, comments) from the API's wrapper structure. + +**Related Classes/Methods**: + +* `QName:`ListingDataExtractor` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py`, Lines:(1:1000) `_ + +ListingParameterMixin +^^^^^^^^^^^^^^^^^^^^^ + +Provides common methods for constructing API paths and parameters required for various types of listings. This ensures consistency and reusability across different listing endpoints. + +**Related Classes/Methods**: + +* `QName:`ListingParameterMixin` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/mixins/base.py`, Lines:(1:1000) `_ + +StreamProcessor +^^^^^^^^^^^^^^^ + +Implements the foundational logic for consuming continuous data streams from the Reddit API. It manages the overall flow, including delays between requests and ensuring resilient fetching. + +**Related Classes/Methods**: + +* `QName:`StreamProcessor` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/util.py`, Lines:(1:1000) `_ + +StreamUniquenessManager +^^^^^^^^^^^^^^^^^^^^^^^ + +Maintains a limited set of recently seen items to ensure uniqueness within a data stream. This prevents reprocessing of duplicate items, which is crucial for real-time data consumption. + +**Related Classes/Methods**: + +* `QName:`StreamUniquenessManager` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/util.py`, Lines:(1:1000) `_ + +StreamBackoffHandler +^^^^^^^^^^^^^^^^^^^^ + +Implements an exponential backoff strategy to manage delays between stream requests. This is critical for respecting API rate limits and preventing excessive requests that could lead to temporary bans. + +**Related Classes/Methods**: + +* `QName:`StreamBackoffHandler` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/util.py`, Lines:(1:1000) `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/.codeboarding/Object_Transformation_Layer.json b/.codeboarding/Object_Transformation_Layer.json index a82420ecd..a7107a99f 100644 --- a/.codeboarding/Object_Transformation_Layer.json +++ b/.codeboarding/Object_Transformation_Layer.json @@ -11,8 +11,7 @@ "reference_start_line": 17, "reference_end_line": 263 } - ], - "can_expand": true + ] }, { "name": "praw.objector.Objector:objectify", @@ -24,8 +23,7 @@ "reference_start_line": 199, "reference_end_line": 279 } - ], - "can_expand": true + ] }, { "name": "praw.objector.Objector:_objectify_dict", @@ -37,8 +35,7 @@ "reference_start_line": 46, "reference_end_line": 197 } - ], - "can_expand": false + ] }, { "name": "praw.objector.Objector:check_error", @@ -50,8 +47,7 @@ "reference_start_line": 6, "reference_end_line": 11 } - ], - "can_expand": false + ] }, { "name": "praw.objector.Objector:parse_error", @@ -63,8 +59,7 @@ "reference_start_line": 13, "reference_end_line": 44 } - ], - "can_expand": false + ] } ], "components_relations": [ diff --git a/.codeboarding/Object_Transformation_Layer.md b/.codeboarding/Object_Transformation_Layer.md deleted file mode 100644 index 92308c366..000000000 --- a/.codeboarding/Object_Transformation_Layer.md +++ /dev/null @@ -1,67 +0,0 @@ -```mermaid -graph LR - praw_objector_Objector["praw.objector.Objector"] - praw_objector_Objector_objectify["praw.objector.Objector:objectify"] - praw_objector_Objector__objectify_dict["praw.objector.Objector:_objectify_dict"] - praw_objector_Objector_check_error["praw.objector.Objector:check_error"] - praw_objector_Objector_parse_error["praw.objector.Objector:parse_error"] - praw_objector_Objector -- "invokes" --> praw_objector_Objector_objectify - praw_objector_Objector -- "invokes" --> praw_objector_Objector_check_error - praw_objector_Objector_objectify -- "utilizes" --> praw_objector_Objector__objectify_dict - praw_objector_Objector_check_error -- "delegates to" --> praw_objector_Objector_parse_error -``` - -[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) - -## Details - -The `praw.objector` subsystem is designed to seamlessly convert raw data from the Reddit API into usable PRAW objects while providing robust error handling. The `Objector` class serves as the central entry point, orchestrating the objectification and error-checking processes. The `objectify` method, with the assistance of `_objectify_dict`, recursively transforms complex data structures into their corresponding PRAW object representations. Concurrently, the `check_error` method, by delegating to `parse_error`, ensures that any API-reported errors are properly identified and converted into structured exceptions, maintaining the integrity and reliability of the data processing pipeline. This clear separation of concerns between data transformation and error management allows for a modular and maintainable architecture. - -### praw.objector.Objector -The central orchestrator of the transformation process, converting raw JSON responses into structured Python objects and managing error detection. It acts as the primary interface for the objectification process. - - -**Related Classes/Methods**: - -- `praw.objector.Objector`:17-263 - - -### praw.objector.Objector:objectify -Implements the core recursive logic for data transformation, traversing raw JSON data, identifying appropriate PRAW object types, and instantiating them. This method is the heart of the data mapping functionality. - - -**Related Classes/Methods**: - -- `praw.objector.Objector:objectify`:199-279 - - -### praw.objector.Objector:_objectify_dict -A specialized helper method for `objectify`, focusing on converting individual dictionary elements within the raw data into their corresponding PRAW object representations. It handles the granular conversion of data structures. - - -**Related Classes/Methods**: - -- `praw.objector.Objector:_objectify_dict`:46-197 - - -### praw.objector.Objector:check_error -Responsible for scanning API responses for error indicators and delegating to `parse_error` if an error is detected. This ensures robust error handling within the transformation pipeline. - - -**Related Classes/Methods**: - -- `praw.objector.Objector:check_error`:6-11 - - -### praw.objector.Objector:parse_error -Interprets raw error data from the API response, converting it into a structured format or raising a specific exception relevant to the PRAW library. This component standardizes error reporting. - - -**Related Classes/Methods**: - -- `praw.objector.Objector:parse_error`:13-44 - - - - -### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) diff --git a/.codeboarding/Object_Transformation_Layer.rst b/.codeboarding/Object_Transformation_Layer.rst new file mode 100644 index 000000000..f2b1ee5eb --- /dev/null +++ b/.codeboarding/Object_Transformation_Layer.rst @@ -0,0 +1,80 @@ +High-level diagram representation of: praw +========================================== + +.. mermaid:: + + graph LR + praw_objector_Objector["praw.objector.Objector"] + praw_objector_Objector_objectify["praw.objector.Objector:objectify"] + praw_objector_Objector__objectify_dict["praw.objector.Objector:_objectify_dict"] + praw_objector_Objector_check_error["praw.objector.Objector:check_error"] + praw_objector_Objector_parse_error["praw.objector.Objector:parse_error"] + praw_objector_Objector -- "invokes" --> praw_objector_Objector_objectify + praw_objector_Objector -- "invokes" --> praw_objector_Objector_check_error + praw_objector_Objector_objectify -- "utilizes" --> praw_objector_Objector__objectify_dict + praw_objector_Objector_check_error -- "delegates to" --> praw_objector_Objector_parse_error + +| |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/GeneratedOnBoardings +.. |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.objector` subsystem is designed to seamlessly convert raw data from the Reddit API into usable PRAW objects while providing robust error handling. The `Objector` class serves as the central entry point, orchestrating the objectification and error-checking processes. The `objectify` method, with the assistance of `_objectify_dict`, recursively transforms complex data structures into their corresponding PRAW object representations. Concurrently, the `check_error` method, by delegating to `parse_error`, ensures that any API-reported errors are properly identified and converted into structured exceptions, maintaining the integrity and reliability of the data processing pipeline. This clear separation of concerns between data transformation and error management allows for a modular and maintainable architecture. + +praw.objector.Objector +^^^^^^^^^^^^^^^^^^^^^^ + +The central orchestrator of the transformation process, converting raw JSON responses into structured Python objects and managing error detection. It acts as the primary interface for the objectification process. + +**Related Classes/Methods**: + +* `QName:`praw.objector.Objector` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py`, Lines:(17:263) `_ + +praw.objector.Objector:objectify +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Implements the core recursive logic for data transformation, traversing raw JSON data, identifying appropriate PRAW object types, and instantiating them. This method is the heart of the data mapping functionality. + +**Related Classes/Methods**: + +* `QName:`praw.objector.Objector:objectify` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py`, Lines:(199:279) `_ + +praw.objector.Objector:_objectify_dict +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A specialized helper method for `objectify`, focusing on converting individual dictionary elements within the raw data into their corresponding PRAW object representations. It handles the granular conversion of data structures. + +**Related Classes/Methods**: + +* `QName:`praw.objector.Objector:_objectify_dict` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py`, Lines:(46:197) `_ + +praw.objector.Objector:check_error +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Responsible for scanning API responses for error indicators and delegating to `parse_error` if an error is detected. This ensures robust error handling within the transformation pipeline. + +**Related Classes/Methods**: + +* `QName:`praw.objector.Objector:check_error` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py`, Lines:(6:11) `_ + +praw.objector.Objector:parse_error +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Interprets raw error data from the API response, converting it into a structured format or raising a specific exception relevant to the PRAW library. This component standardizes error reporting. + +**Related Classes/Methods**: + +* `QName:`praw.objector.Objector:parse_error` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py`, Lines:(13:44) `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/.codeboarding/Reddit_Data_Models.json b/.codeboarding/Reddit_Data_Models.json index a449a84f7..9b32e3ace 100644 --- a/.codeboarding/Reddit_Data_Models.json +++ b/.codeboarding/Reddit_Data_Models.json @@ -11,8 +11,7 @@ "reference_start_line": 2446, "reference_end_line": 2446 } - ], - "can_expand": true + ] }, { "name": "Submission", @@ -24,8 +23,7 @@ "reference_start_line": 716, "reference_end_line": 716 } - ], - "can_expand": true + ] }, { "name": "Comment", @@ -37,8 +35,7 @@ "reference_start_line": 582, "reference_end_line": 596 } - ], - "can_expand": false + ] }, { "name": "Redditor", @@ -50,8 +47,7 @@ "reference_start_line": 810, "reference_end_line": 819 } - ], - "can_expand": true + ] }, { "name": "VotableMixin", @@ -63,8 +59,7 @@ "reference_start_line": 8, "reference_end_line": 92 } - ], - "can_expand": false + ] }, { "name": "Modmail", @@ -76,8 +71,7 @@ "reference_start_line": 2627, "reference_end_line": 2639 } - ], - "can_expand": true + ] }, { "name": "LiveThread", @@ -89,8 +83,7 @@ "reference_start_line": 261, "reference_end_line": 471 } - ], - "can_expand": true + ] }, { "name": "WikiPage", @@ -102,8 +95,7 @@ "reference_start_line": 146, "reference_end_line": 314 } - ], - "can_expand": false + ] } ], "components_relations": [ diff --git a/.codeboarding/Reddit_Data_Models.md b/.codeboarding/Reddit_Data_Models.md deleted file mode 100644 index 6ff2267f5..000000000 --- a/.codeboarding/Reddit_Data_Models.md +++ /dev/null @@ -1,100 +0,0 @@ -```mermaid -graph LR - Subreddit["Subreddit"] - Submission["Submission"] - Comment["Comment"] - Redditor["Redditor"] - VotableMixin["VotableMixin"] - Modmail["Modmail"] - LiveThread["LiveThread"] - WikiPage["WikiPage"] - Subreddit -- "creates and fetches" --> Submission - Subreddit -- "composes" --> Modmail - Submission -- "retrieves and references" --> Comment - Submission -- "inherits from" --> VotableMixin - Comment -- "inherits from" --> VotableMixin - Modmail -- "involves" --> Redditor - WikiPage -- "associated with" --> Subreddit -``` - -[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) - -## Details - -The PRAW library's core architecture for interacting with Reddit content is centered around key models representing Reddit entities. The Subreddit component acts as a central hub for community-specific interactions, enabling the creation and retrieval of Submission objects. Submission objects, in turn, manage post data and facilitate interactions with Comment threads. Both Submission and Comment leverage the VotableMixin for consistent voting functionality, demonstrating effective code reuse through inheritance. User-centric operations are handled by the Redditor component, which is involved in Modmail conversations. Modmail itself is composed by Subreddit, indicating its role in community moderation. LiveThread and WikiPage represent distinct content streams and informational pages, with WikiPage being directly associated with a Subreddit. This design emphasizes a clear separation of concerns, with each component encapsulating specific Reddit functionality and interacting through well-defined relationships to manage and present Reddit data. - -### Subreddit -Manages subreddit data, submissions, moderation, flair, and style. It acts as a primary facade for subreddit-specific API calls, allowing users to interact with a community's content and settings. - - -**Related Classes/Methods**: - -- `praw.models.reddit.subreddit.Subreddit` - - -### Submission -Encapsulates Reddit post data, including content, flair, and moderation status. It provides methods for retrieving content and interacting with the post (e.g., voting, commenting). - - -**Related Classes/Methods**: - -- `praw.models.reddit.submission.Submission` - - -### Comment -Manages individual comment data, including its content, author, and hierarchical position within a discussion. It provides methods for moderation and navigating comment threads. - - -**Related Classes/Methods**: - -- `Comment`:582-596 - - -### Redditor -Provides access to user-specific information, including profile details, submitted content, and comments. It enables interactions related to a specific Reddit user. - - -**Related Classes/Methods**: - -- `Redditor`:810-819 - - -### VotableMixin -A mixin class that provides common voting functionality (upvote, downvote, clear vote) to any Reddit entity that can be voted on. This promotes code reuse and consistency across votable models. - - -**Related Classes/Methods**: - -- `VotableMixin`:8-92 - - -### Modmail -Represents a modmail conversation, facilitating communication between moderators and users, or between moderators themselves. It encapsulates messages and conversation states. - - -**Related Classes/Methods**: - -- `Modmail`:2627-2639 - - -### LiveThread -Manages data and interactions for Reddit Live Threads, which are real-time, event-driven content streams. It provides access to updates and thread metadata. - - -**Related Classes/Methods**: - -- `LiveThread`:261-471 - - -### WikiPage -Abstracts the content and moderation aspects of a Reddit Wiki Page. It allows for retrieval, editing, and management of wiki content within a subreddit. - - -**Related Classes/Methods**: - -- `WikiPage`:146-314 - - - - -### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) diff --git a/.codeboarding/Reddit_Data_Models.rst b/.codeboarding/Reddit_Data_Models.rst new file mode 100644 index 000000000..092d56819 --- /dev/null +++ b/.codeboarding/Reddit_Data_Models.rst @@ -0,0 +1,113 @@ +High-level diagram representation of: praw +========================================== + +.. mermaid:: + + graph LR + Subreddit["Subreddit"] + Submission["Submission"] + Comment["Comment"] + Redditor["Redditor"] + VotableMixin["VotableMixin"] + Modmail["Modmail"] + LiveThread["LiveThread"] + WikiPage["WikiPage"] + Subreddit -- "creates and fetches" --> Submission + Subreddit -- "composes" --> Modmail + Submission -- "retrieves and references" --> Comment + Submission -- "inherits from" --> VotableMixin + Comment -- "inherits from" --> VotableMixin + Modmail -- "involves" --> Redditor + WikiPage -- "associated with" --> Subreddit + +| |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/GeneratedOnBoardings +.. |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 for interacting with Reddit content is centered around key models representing Reddit entities. The Subreddit component acts as a central hub for community-specific interactions, enabling the creation and retrieval of Submission objects. Submission objects, in turn, manage post data and facilitate interactions with Comment threads. Both Submission and Comment leverage the VotableMixin for consistent voting functionality, demonstrating effective code reuse through inheritance. User-centric operations are handled by the Redditor component, which is involved in Modmail conversations. Modmail itself is composed by Subreddit, indicating its role in community moderation. LiveThread and WikiPage represent distinct content streams and informational pages, with WikiPage being directly associated with a Subreddit. This design emphasizes a clear separation of concerns, with each component encapsulating specific Reddit functionality and interacting through well-defined relationships to manage and present Reddit data. + +Subreddit +^^^^^^^^^ + +Manages subreddit data, submissions, moderation, flair, and style. It acts as a primary facade for subreddit-specific API calls, allowing users to interact with a community's content and settings. + +**Related Classes/Methods**: + +* `QName:`praw.models.reddit.subreddit.Subreddit` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/subreddit.py` `_ + +Submission +^^^^^^^^^^ + +Encapsulates Reddit post data, including content, flair, and moderation status. It provides methods for retrieving content and interacting with the post (e.g., voting, commenting). + +**Related Classes/Methods**: + +* `QName:`praw.models.reddit.submission.Submission` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/submission.py` `_ + +Comment +^^^^^^^ + +Manages individual comment data, including its content, author, and hierarchical position within a discussion. It provides methods for moderation and navigating comment threads. + +**Related Classes/Methods**: + +* `QName:`Comment` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py`, Lines:(582:596) `_ + +Redditor +^^^^^^^^ + +Provides access to user-specific information, including profile details, submitted content, and comments. It enables interactions related to a specific Reddit user. + +**Related Classes/Methods**: + +* `QName:`Redditor` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py`, Lines:(810:819) `_ + +VotableMixin +^^^^^^^^^^^^ + +A mixin class that provides common voting functionality (upvote, downvote, clear vote) to any Reddit entity that can be voted on. This promotes code reuse and consistency across votable models. + +**Related Classes/Methods**: + +* `QName:`VotableMixin` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/votable.py`, Lines:(8:92) `_ + +Modmail +^^^^^^^ + +Represents a modmail conversation, facilitating communication between moderators and users, or between moderators themselves. It encapsulates messages and conversation states. + +**Related Classes/Methods**: + +* `QName:`Modmail` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/subreddit.py`, Lines:(2627:2639) `_ + +LiveThread +^^^^^^^^^^ + +Manages data and interactions for Reddit Live Threads, which are real-time, event-driven content streams. It provides access to updates and thread metadata. + +**Related Classes/Methods**: + +* `QName:`LiveThread` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/live.py`, Lines:(261:471) `_ + +WikiPage +^^^^^^^^ + +Abstracts the content and moderation aspects of a Reddit Wiki Page. It allows for retrieval, editing, and management of wiki content within a subreddit. + +**Related Classes/Methods**: + +* `QName:`WikiPage` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/wikipage.py`, Lines:(146:314) `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/.codeboarding/analysis.json b/.codeboarding/analysis.json index 48c04209f..c12ed25c3 100644 --- a/.codeboarding/analysis.json +++ b/.codeboarding/analysis.json @@ -143,7 +143,7 @@ "reference_end_line": 189 } ], - "can_expand": true + "can_expand": false } ], "components_relations": [ diff --git a/.codeboarding/codeboarding_version.json b/.codeboarding/codeboarding_version.json index c309e60c7..0a1d38493 100644 --- a/.codeboarding/codeboarding_version.json +++ b/.codeboarding/codeboarding_version.json @@ -1,4 +1,4 @@ { - "commit_hash": "f2a2e7884e4c4cd77887970471d090bd0da12349", + "commit_hash": "3acb442f380f1d496c53de659f5f1a03b633f325", "code_boarding_version": "0.1.0" } diff --git a/.codeboarding/on_boarding.md b/.codeboarding/on_boarding.md deleted file mode 100644 index c71e4e9cc..000000000 --- a/.codeboarding/on_boarding.md +++ /dev/null @@ -1,101 +0,0 @@ -```mermaid -graph LR - API_Client_Core["API Client Core"] - Configuration_Manager["Configuration Manager"] - Object_Transformation_Layer["Object Transformation Layer"] - Reddit_Data_Models["Reddit Data Models"] - Listing_Stream_Processors["Listing & Stream Processors"] - Exception_Handling["Exception Handling"] - API_Client_Core -- "uses" --> Configuration_Manager - API_Client_Core -- "sends raw responses to" --> Object_Transformation_Layer - API_Client_Core -- "reports errors to" --> Exception_Handling - Object_Transformation_Layer -- "receives raw responses from" --> API_Client_Core - Object_Transformation_Layer -- "instantiates" --> Reddit_Data_Models - Object_Transformation_Layer -- "parses errors with" --> Exception_Handling - Reddit_Data_Models -- "initiates requests via" --> API_Client_Core - Reddit_Data_Models -- "are utilized by" --> Listing_Stream_Processors - Listing_Stream_Processors -- "fetches batches via" --> API_Client_Core - Listing_Stream_Processors -- "utilizes" --> Reddit_Data_Models - Exception_Handling -- "receives errors from" --> API_Client_Core - Exception_Handling -- "receives parsed errors from" --> Object_Transformation_Layer - click API_Client_Core href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/API_Client_Core.md" "Details" - click Object_Transformation_Layer href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Object_Transformation_Layer.md" "Details" - click Reddit_Data_Models href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Reddit_Data_Models.md" "Details" - click Listing_Stream_Processors href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Listing_Stream_Processors.md" "Details" - click Exception_Handling href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Exception_Handling.md" "Details" -``` - -[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) - -## Details - -The PRAW architecture is designed as a robust API wrapper, providing an object-oriented interface to the Reddit API. It centers around the `API Client Core`, which orchestrates all network interactions, leveraging the `Configuration Manager` for settings and delegating raw response processing to the `Object Transformation Layer`. This layer is responsible for mapping raw API data into rich `Reddit Data Models`, which encapsulate Reddit entities and their behaviors. For handling collections and real-time data, the `Listing & Stream Processors` work in conjunction with the `API Client Core` and `Reddit Data Models`. Critical to its reliability, the `Exception Handling` component provides structured error reporting across the system. This design ensures a clear separation of concerns, facilitating maintainability, extensibility, and a developer-friendly experience, making it ideal for both documentation and visual flow graph representation. - -### API Client Core [[Expand]](./API_Client_Core.md) -The central orchestrator for all interactions with the Reddit API, managing HTTP requests, authentication, and rate limiting. - - -**Related Classes/Methods**: - -- `praw.reddit.Reddit.__init__` -- `praw.reddit.Reddit.request` -- `praw.reddit.Reddit._objectify_request` -- `praw.reddit.Reddit._handle_rate_limit` - - -### Configuration Manager -Handles the loading, storage, and provision of PRAW's operational settings, including API credentials and user agent strings. - - -**Related Classes/Methods**: - -- `praw.config.Config.__init__` -- `praw.config.Config._load_config` - - -### Object Transformation Layer [[Expand]](./Object_Transformation_Layer.md) -Acts as a data mapper, converting raw JSON responses from the Reddit API into rich, object-oriented Python representations (`Reddit Data Models`). - - -**Related Classes/Methods**: - -- `praw.objector.Objector.objectify` -- `praw.objector.Objector.check_error` - - -### Reddit Data Models [[Expand]](./Reddit_Data_Models.md) -A comprehensive set of classes representing various Reddit entities (e.g., `Subreddit`, `Submission`, `Comment`, `Redditor`). These models encapsulate data and provide high-level methods for interacting with their respective API endpoints. - - -**Related Classes/Methods**: - -- `praw.models.reddit.subreddit.Subreddit.submit` -- `praw.models.reddit.submission.Submission._fetch_data` -- `praw.models.reddit.comment.Comment.parent` -- `praw.models.reddit.redditor.Redditor._fetch_info` -- `praw.models.reddit.mixins.votable.VotableMixin._vote` - - -### Listing & Stream Processors [[Expand]](./Listing_Stream_Processors.md) -Provides mechanisms for iterating through paginated API responses (listings) and consuming real-time data streams from Reddit, handling pagination logic and item uniqueness. - - -**Related Classes/Methods**: - -- `praw.models.listing.generator.ListingGenerator.__next__` -- `praw.models.listing.generator.ListingGenerator._next_batch` - - -### Exception Handling [[Expand]](./Exception_Handling.md) -Defines a hierarchy of custom exception classes specific to PRAW and provides utilities to translate raw API error messages into structured exceptions. - - -**Related Classes/Methods**: - -- `praw.exceptions.PRAWException`:14-15 -- `praw.exceptions.parse_exception_list`:173-189 - - - - -### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) diff --git a/.codeboarding/on_boarding.rst b/.codeboarding/on_boarding.rst new file mode 100644 index 000000000..252f39898 --- /dev/null +++ b/.codeboarding/on_boarding.rst @@ -0,0 +1,121 @@ +High-level diagram representation of: praw +========================================== + +.. mermaid:: + + graph LR + API_Client_Core["API Client Core"] + Configuration_Manager["Configuration Manager"] + Object_Transformation_Layer["Object Transformation Layer"] + Reddit_Data_Models["Reddit Data Models"] + Listing_Stream_Processors["Listing & Stream Processors"] + Exception_Handling["Exception Handling"] + API_Client_Core -- "uses" --> Configuration_Manager + API_Client_Core -- "sends raw responses to" --> Object_Transformation_Layer + API_Client_Core -- "reports errors to" --> Exception_Handling + Object_Transformation_Layer -- "receives raw responses from" --> API_Client_Core + Object_Transformation_Layer -- "instantiates" --> Reddit_Data_Models + Object_Transformation_Layer -- "parses errors with" --> Exception_Handling + Reddit_Data_Models -- "initiates requests via" --> API_Client_Core + Reddit_Data_Models -- "are utilized by" --> Listing_Stream_Processors + Listing_Stream_Processors -- "fetches batches via" --> API_Client_Core + Listing_Stream_Processors -- "utilizes" --> Reddit_Data_Models + Exception_Handling -- "receives errors from" --> API_Client_Core + Exception_Handling -- "receives parsed errors from" --> Object_Transformation_Layer + click API_Client_Core href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/API_Client_Core.html" "Details" + click Object_Transformation_Layer href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Object_Transformation_Layer.html" "Details" + click Reddit_Data_Models href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Reddit_Data_Models.html" "Details" + click Listing_Stream_Processors href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Listing_Stream_Processors.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/GeneratedOnBoardings +.. |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 architecture is designed as a robust API wrapper, providing an object-oriented interface to the Reddit API. It centers around the `API Client Core`, which orchestrates all network interactions, leveraging the `Configuration Manager` for settings and delegating raw response processing to the `Object Transformation Layer`. This layer is responsible for mapping raw API data into rich `Reddit Data Models`, which encapsulate Reddit entities and their behaviors. For handling collections and real-time data, the `Listing & Stream Processors` work in conjunction with the `API Client Core` and `Reddit Data Models`. Critical to its reliability, the `Exception Handling` component provides structured error reporting across the system. This design ensures a clear separation of concerns, facilitating maintainability, extensibility, and a developer-friendly experience, making it ideal for both documentation and visual flow graph representation. + +API Client Core +^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +The central orchestrator for all interactions with the Reddit API, managing HTTP requests, authentication, and rate limiting. + +**Related Classes/Methods**: + +* `QName:`praw.reddit.Reddit.__init__` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` `_ +* `QName:`praw.reddit.Reddit.request` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` `_ +* `QName:`praw.reddit.Reddit._objectify_request` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` `_ +* `QName:`praw.reddit.Reddit._handle_rate_limit` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` `_ + +Configuration Manager +^^^^^^^^^^^^^^^^^^^^^ + +Handles the loading, storage, and provision of PRAW's operational settings, including API credentials and user agent strings. + +**Related Classes/Methods**: + +* `QName:`praw.config.Config.__init__` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/config.py` `_ +* `QName:`praw.config.Config._load_config` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/config.py` `_ + +Object Transformation Layer +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +Acts as a data mapper, converting raw JSON responses from the Reddit API into rich, object-oriented Python representations (`Reddit Data Models`). + +**Related Classes/Methods**: + +* `QName:`praw.objector.Objector.objectify` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py` `_ +* `QName:`praw.objector.Objector.check_error` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py` `_ + +Reddit Data Models +^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +A comprehensive set of classes representing various Reddit entities (e.g., `Subreddit`, `Submission`, `Comment`, `Redditor`). These models encapsulate data and provide high-level methods for interacting with their respective API endpoints. + +**Related Classes/Methods**: + +* `QName:`praw.models.reddit.subreddit.Subreddit.submit` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/subreddit.py` `_ +* `QName:`praw.models.reddit.submission.Submission._fetch_data` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/submission.py` `_ +* `QName:`praw.models.reddit.comment.Comment.parent` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/comment.py` `_ +* `QName:`praw.models.reddit.redditor.Redditor._fetch_info` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/redditor.py` `_ +* `QName:`praw.models.reddit.mixins.votable.VotableMixin._vote` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/votable.py` `_ + +Listing & Stream Processors +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +Provides mechanisms for iterating through paginated API responses (listings) and consuming real-time data streams from Reddit, handling pagination logic and item uniqueness. + +**Related Classes/Methods**: + +* `QName:`praw.models.listing.generator.ListingGenerator.__next__` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py` `_ +* `QName:`praw.models.listing.generator.ListingGenerator._next_batch` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py` `_ + +Exception Handling +^^^^^^^^^^^^^^^^^^ + +Defines a hierarchy of custom exception classes specific to PRAW and provides utilities to translate raw API error messages into structured exceptions. + +**Related Classes/Methods**: + +* `QName:`praw.exceptions.PRAWException` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py`, Lines:(14:15) `_ +* `QName:`praw.exceptions.parse_exception_list` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py`, Lines:(173:189) `_ + + +FAQ +--- + +`See the FAQ `_ From 55a62c2721b4753a54b0917d591e96b49bfd9b87 Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Mon, 1 Sep 2025 18:37:23 +0000 Subject: [PATCH 07/23] docs: update codeboarding documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 📚 Documentation Update This commit contains updated documentation files fetched from the CodeBoarding service. ### 📊 Summary - Documentation files created/updated: 6 - JSON files created/updated: 7 - Documentation directory: .codeboarding/ - JSON directory: .codeboarding/ - Output format: .rst - Repository analyzed: https://github.com/praw-dev/praw - Source branch: main - Target branch: main 🤖 This commit was automatically generated by the CodeBoarding documentation update workflow. --- .codeboarding/API_Client_Core.rst | 34 +++---- .codeboarding/Exception_Handling.json | 92 +++++++++++++++++++ .codeboarding/Exception_Handling.rst | 80 ++++++++++++++++ .codeboarding/Listing_Stream_Processors.rst | 20 ++-- .codeboarding/Object_Transformation_Layer.rst | 16 ++-- .codeboarding/Reddit_Data_Models.rst | 22 ++--- .codeboarding/analysis.json | 2 +- .codeboarding/codeboarding_version.json | 2 +- .../{on_boarding.rst => overview.rst} | 51 +++++----- 9 files changed, 247 insertions(+), 72 deletions(-) create mode 100644 .codeboarding/Exception_Handling.json create mode 100644 .codeboarding/Exception_Handling.rst rename .codeboarding/{on_boarding.rst => overview.rst} (50%) diff --git a/.codeboarding/API_Client_Core.rst b/.codeboarding/API_Client_Core.rst index 785f79d72..a71c8d5b6 100644 --- a/.codeboarding/API_Client_Core.rst +++ b/.codeboarding/API_Client_Core.rst @@ -1,5 +1,5 @@ -High-level diagram representation of: praw -========================================== +Api Client Core +=============== .. mermaid:: @@ -21,12 +21,12 @@ High-level diagram representation of: praw Request_Executor -- "returns raw response to" --> Response_Objectifier Response_Objectifier -- "transforms for" --> API_Operation_Methods API_Operation_Methods -- "consults" --> Rate_Limit_Manager - click API_Client_Core href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/API_Client_Core.html" "Details" + click API_Client_Core href "https://github.com/praw-dev/praw/blob/main/.codeboarding/API_Client_Core.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/GeneratedOnBoardings + :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 @@ -46,7 +46,7 @@ Serves as the main entry point for users to interact with the Reddit API. It orc **Related Classes/Methods**: -* `QName:`praw.reddit.Reddit` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py`, Lines:(57:901) `_ +* `praw.reddit.Reddit:57-901 `_ Client Initializer ^^^^^^^^^^^^^^^^^^ @@ -55,9 +55,9 @@ Sets up the API Client Core instance, including configuring the underlying HTTP **Related Classes/Methods**: -* `QName:`praw.reddit.Reddit.__init__` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` `_ -* `QName:`praw.reddit._prepare_prawcore` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py`, Lines:(527:546) `_ -* `QName:`praw.reddit._prepare_objector` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py`, Lines:(479:525) `_ +* `praw.reddit.Reddit.__init__ `_ +* `praw.reddit._prepare_prawcore:527-546 `_ +* `praw.reddit._prepare_objector:479-525 `_ Request Executor ^^^^^^^^^^^^^^^^ @@ -66,7 +66,7 @@ Executes the raw HTTP requests to the Reddit API, handling the low-level communi **Related Classes/Methods**: -* `QName:`praw.reddit.Reddit.request` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` `_ +* `praw.reddit.Reddit.request `_ Response Objectifier ^^^^^^^^^^^^^^^^^^^^ @@ -75,7 +75,7 @@ Transforms the raw JSON responses from the API into structured PRAW Python objec **Related Classes/Methods**: -* `QName:`praw.reddit.Reddit._objectify_request` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` `_ +* `praw.reddit.Reddit._objectify_request `_ Rate Limit Manager ^^^^^^^^^^^^^^^^^^ @@ -84,7 +84,7 @@ Monitors and enforces Reddit's API rate limits, pausing requests when necessary **Related Classes/Methods**: -* `QName:`praw.reddit.Reddit._handle_rate_limit` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` `_ +* `praw.reddit.Reddit._handle_rate_limit `_ API Operation Methods ^^^^^^^^^^^^^^^^^^^^^ @@ -93,11 +93,11 @@ Provide specific, high-level methods for common API operations (e.g., fetching d **Related Classes/Methods**: -* `QName:`praw.reddit.Reddit.get` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` `_ -* `QName:`praw.reddit.Reddit.post` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` `_ -* `QName:`praw.reddit.Reddit.delete` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` `_ -* `QName:`praw.reddit.Reddit.patch` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` `_ -* `QName:`praw.reddit.Reddit.put` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` `_ +* `praw.reddit.Reddit.get `_ +* `praw.reddit.Reddit.post `_ +* `praw.reddit.Reddit.delete `_ +* `praw.reddit.Reddit.patch `_ +* `praw.reddit.Reddit.put `_ Async Checker ^^^^^^^^^^^^^ @@ -106,7 +106,7 @@ Manages and verifies the asynchronous context for operations, ensuring proper ex **Related Classes/Methods**: -* `QName:`praw.reddit._check_for_async` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py`, Lines:(388:411) `_ +* `praw.reddit._check_for_async:388-411 `_ FAQ diff --git a/.codeboarding/Exception_Handling.json b/.codeboarding/Exception_Handling.json new file mode 100644 index 000000000..dbef45d40 --- /dev/null +++ b/.codeboarding/Exception_Handling.json @@ -0,0 +1,92 @@ +{ + "description": "The PRAW error handling subsystem efficiently processes raw API responses into structured, actionable exceptions. The `ErrorDetector` initiates the process by identifying potential errors in API responses, subsequently delegating their detailed parsing to the `ExceptionFactory`. The `ExceptionFactory` then leverages the `ErrorParser` to transform raw error data into standardized `ErrorItem` objects. Finally, based on these structured error details, the `ExceptionFactory` constructs and raises appropriate custom exceptions, all derived from the foundational `ExceptionBase`, providing a consistent and predictable error interface for developers.", + "components": [ + { + "name": "ExceptionBase", + "description": "The foundational base class for all custom exceptions within PRAW. It establishes a consistent error handling mechanism across the library and provides a unified structure for reporting and handling errors. This is critical for an API wrapper to provide a predictable error interface to developers.", + "referenced_source_code": [ + { + "qualified_name": "praw.exceptions.PRAWException", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py", + "reference_start_line": 14, + "reference_end_line": 15 + } + ], + "can_expand": false + }, + { + "name": "ErrorItem", + "description": "A data structure that encapsulates the details of a single, specific error returned by the Reddit API. It provides a standardized and easily accessible format for error information, transforming raw API responses into structured, consumable objects. This component is vital for abstracting raw API error messages into a developer-friendly format.", + "referenced_source_code": [ + { + "qualified_name": "praw.exceptions.RedditErrorItem", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py", + "reference_start_line": 18, + "reference_end_line": 71 + } + ], + "can_expand": false + }, + { + "name": "ErrorParser", + "description": "A crucial utility function responsible for transforming raw, unstructured error data received from the Reddit API into a list of structured `ErrorItem` objects. It acts as a parser, converting raw error dictionaries into `praw.exceptions.RedditErrorItem` instances, which is essential for making API errors manageable.", + "referenced_source_code": [ + { + "qualified_name": "praw.exceptions.parse_exception_list", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py", + "reference_start_line": 173, + "reference_end_line": 189 + } + ], + "can_expand": false + }, + { + "name": "ErrorDetector", + "description": "The initial entry point for error detection within API responses. It acts as a preliminary gatekeeper that identifies potential errors in the raw API response and delegates further processing. This component is the first line of defense in the error handling pipeline, ensuring that only responses with potential errors are further processed.", + "referenced_source_code": [ + { + "qualified_name": "praw.objector.check_error", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py", + "reference_start_line": 20, + "reference_end_line": 24 + } + ], + "can_expand": false + }, + { + "name": "ExceptionFactory", + "description": "The core orchestrator for converting raw API error structures into PRAW-specific exception objects. It manages the flow from raw error data to structured exceptions, acting as an adapter between the raw API error format and PRAW's internal exception system. This component is central to raising appropriate, custom exceptions for the API wrapper.", + "referenced_source_code": [ + { + "qualified_name": "praw.objector.parse_error", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py", + "reference_start_line": 26, + "reference_end_line": 48 + } + ], + "can_expand": true + } + ], + "components_relations": [ + { + "relation": "delegates error parsing to", + "src_name": "ErrorDetector", + "dst_name": "ExceptionFactory" + }, + { + "relation": "converts raw errors to structured items via", + "src_name": "ExceptionFactory", + "dst_name": "ErrorParser" + }, + { + "relation": "creates", + "src_name": "ErrorParser", + "dst_name": "ErrorItem" + }, + { + "relation": "raises", + "src_name": "ExceptionFactory", + "dst_name": "ExceptionBase" + } + ] +} diff --git a/.codeboarding/Exception_Handling.rst b/.codeboarding/Exception_Handling.rst new file mode 100644 index 000000000..847c6a78e --- /dev/null +++ b/.codeboarding/Exception_Handling.rst @@ -0,0 +1,80 @@ +Exception Handling +================== + +.. mermaid:: + + graph LR + ExceptionBase["ExceptionBase"] + ErrorItem["ErrorItem"] + ErrorParser["ErrorParser"] + ErrorDetector["ErrorDetector"] + ExceptionFactory["ExceptionFactory"] + ErrorDetector -- "delegates error parsing to" --> ExceptionFactory + ExceptionFactory -- "converts raw errors to structured items via" --> ErrorParser + ErrorParser -- "creates" --> ErrorItem + ExceptionFactory -- "raises" --> ExceptionBase + +| |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 error handling subsystem efficiently processes raw API responses into structured, actionable exceptions. The `ErrorDetector` initiates the process by identifying potential errors in API responses, subsequently delegating their detailed parsing to the `ExceptionFactory`. The `ExceptionFactory` then leverages the `ErrorParser` to transform raw error data into standardized `ErrorItem` objects. Finally, based on these structured error details, the `ExceptionFactory` constructs and raises appropriate custom exceptions, all derived from the foundational `ExceptionBase`, providing a consistent and predictable error interface for developers. + +ExceptionBase +^^^^^^^^^^^^^ + +The foundational base class for all custom exceptions within PRAW. It establishes a consistent error handling mechanism across the library and provides a unified structure for reporting and handling errors. This is critical for an API wrapper to provide a predictable error interface to developers. + +**Related Classes/Methods**: + +* `praw.exceptions.PRAWException:14-15 `_ + +ErrorItem +^^^^^^^^^ + +A data structure that encapsulates the details of a single, specific error returned by the Reddit API. It provides a standardized and easily accessible format for error information, transforming raw API responses into structured, consumable objects. This component is vital for abstracting raw API error messages into a developer-friendly format. + +**Related Classes/Methods**: + +* `praw.exceptions.RedditErrorItem:18-71 `_ + +ErrorParser +^^^^^^^^^^^ + +A crucial utility function responsible for transforming raw, unstructured error data received from the Reddit API into a list of structured `ErrorItem` objects. It acts as a parser, converting raw error dictionaries into `praw.exceptions.RedditErrorItem` instances, which is essential for making API errors manageable. + +**Related Classes/Methods**: + +* `praw.exceptions.parse_exception_list:173-189 `_ + +ErrorDetector +^^^^^^^^^^^^^ + +The initial entry point for error detection within API responses. It acts as a preliminary gatekeeper that identifies potential errors in the raw API response and delegates further processing. This component is the first line of defense in the error handling pipeline, ensuring that only responses with potential errors are further processed. + +**Related Classes/Methods**: + +* `praw.objector.check_error:20-24 `_ + +ExceptionFactory +^^^^^^^^^^^^^^^^ + +The core orchestrator for converting raw API error structures into PRAW-specific exception objects. It manages the flow from raw error data to structured exceptions, acting as an adapter between the raw API error format and PRAW's internal exception system. This component is central to raising appropriate, custom exceptions for the API wrapper. + +**Related Classes/Methods**: + +* `praw.objector.parse_error:26-48 `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/.codeboarding/Listing_Stream_Processors.rst b/.codeboarding/Listing_Stream_Processors.rst index bdb692166..ec5a2a4fa 100644 --- a/.codeboarding/Listing_Stream_Processors.rst +++ b/.codeboarding/Listing_Stream_Processors.rst @@ -1,5 +1,5 @@ -High-level diagram representation of: praw -========================================== +Listing Stream Processors +========================= .. mermaid:: @@ -24,7 +24,7 @@ High-level diagram representation of: praw | |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/GeneratedOnBoardings + :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 @@ -42,7 +42,7 @@ Provides an iterable interface for consuming paginated API responses. It manages **Related Classes/Methods**: -* `QName:`ListingGenerator` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py`, Lines:(17:103) `_ +* `ListingGenerator:17-103 `_ ListingBatchFetcher ^^^^^^^^^^^^^^^^^^^ @@ -51,7 +51,7 @@ Responsible for fetching a single batch of items from the Reddit API using the u **Related Classes/Methods**: -* `QName:`ListingBatchFetcher` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py`, Lines:(1:1000) `_ +* `ListingBatchFetcher:1-1000 `_ ListingDataExtractor ^^^^^^^^^^^^^^^^^^^^ @@ -60,7 +60,7 @@ Parses the raw JSON response received from the API, isolating and returning the **Related Classes/Methods**: -* `QName:`ListingDataExtractor` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py`, Lines:(1:1000) `_ +* `ListingDataExtractor:1-1000 `_ ListingParameterMixin ^^^^^^^^^^^^^^^^^^^^^ @@ -69,7 +69,7 @@ Provides common methods for constructing API paths and parameters required for v **Related Classes/Methods**: -* `QName:`ListingParameterMixin` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/mixins/base.py`, Lines:(1:1000) `_ +* `ListingParameterMixin:1-1000 `_ StreamProcessor ^^^^^^^^^^^^^^^ @@ -78,7 +78,7 @@ Implements the foundational logic for consuming continuous data streams from the **Related Classes/Methods**: -* `QName:`StreamProcessor` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/util.py`, Lines:(1:1000) `_ +* `StreamProcessor:1-1000 `_ StreamUniquenessManager ^^^^^^^^^^^^^^^^^^^^^^^ @@ -87,7 +87,7 @@ Maintains a limited set of recently seen items to ensure uniqueness within a dat **Related Classes/Methods**: -* `QName:`StreamUniquenessManager` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/util.py`, Lines:(1:1000) `_ +* `StreamUniquenessManager:1-1000 `_ StreamBackoffHandler ^^^^^^^^^^^^^^^^^^^^ @@ -96,7 +96,7 @@ Implements an exponential backoff strategy to manage delays between stream reque **Related Classes/Methods**: -* `QName:`StreamBackoffHandler` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/util.py`, Lines:(1:1000) `_ +* `StreamBackoffHandler:1-1000 `_ FAQ diff --git a/.codeboarding/Object_Transformation_Layer.rst b/.codeboarding/Object_Transformation_Layer.rst index f2b1ee5eb..2fccb831b 100644 --- a/.codeboarding/Object_Transformation_Layer.rst +++ b/.codeboarding/Object_Transformation_Layer.rst @@ -1,5 +1,5 @@ -High-level diagram representation of: praw -========================================== +Object Transformation Layer +=========================== .. mermaid:: @@ -17,7 +17,7 @@ High-level diagram representation of: praw | |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/GeneratedOnBoardings + :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 @@ -35,7 +35,7 @@ The central orchestrator of the transformation process, converting raw JSON resp **Related Classes/Methods**: -* `QName:`praw.objector.Objector` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py`, Lines:(17:263) `_ +* `praw.objector.Objector:17-263 `_ praw.objector.Objector:objectify ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -44,7 +44,7 @@ Implements the core recursive logic for data transformation, traversing raw JSON **Related Classes/Methods**: -* `QName:`praw.objector.Objector:objectify` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py`, Lines:(199:279) `_ +* `praw.objector.Objector:objectify:199-279 `_ praw.objector.Objector:_objectify_dict ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -53,7 +53,7 @@ A specialized helper method for `objectify`, focusing on converting individual d **Related Classes/Methods**: -* `QName:`praw.objector.Objector:_objectify_dict` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py`, Lines:(46:197) `_ +* `praw.objector.Objector:_objectify_dict:46-197 `_ praw.objector.Objector:check_error ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -62,7 +62,7 @@ Responsible for scanning API responses for error indicators and delegating to `p **Related Classes/Methods**: -* `QName:`praw.objector.Objector:check_error` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py`, Lines:(6:11) `_ +* `praw.objector.Objector:check_error:6-11 `_ praw.objector.Objector:parse_error ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -71,7 +71,7 @@ Interprets raw error data from the API response, converting it into a structured **Related Classes/Methods**: -* `QName:`praw.objector.Objector:parse_error` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py`, Lines:(13:44) `_ +* `praw.objector.Objector:parse_error:13-44 `_ FAQ diff --git a/.codeboarding/Reddit_Data_Models.rst b/.codeboarding/Reddit_Data_Models.rst index 092d56819..d6e6f9d3a 100644 --- a/.codeboarding/Reddit_Data_Models.rst +++ b/.codeboarding/Reddit_Data_Models.rst @@ -1,5 +1,5 @@ -High-level diagram representation of: praw -========================================== +Reddit Data Models +================== .. mermaid:: @@ -23,7 +23,7 @@ High-level diagram representation of: praw | |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/GeneratedOnBoardings + :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 @@ -41,7 +41,7 @@ Manages subreddit data, submissions, moderation, flair, and style. It acts as a **Related Classes/Methods**: -* `QName:`praw.models.reddit.subreddit.Subreddit` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/subreddit.py` `_ +* `praw.models.reddit.subreddit.Subreddit `_ Submission ^^^^^^^^^^ @@ -50,7 +50,7 @@ Encapsulates Reddit post data, including content, flair, and moderation status. **Related Classes/Methods**: -* `QName:`praw.models.reddit.submission.Submission` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/submission.py` `_ +* `praw.models.reddit.submission.Submission `_ Comment ^^^^^^^ @@ -59,7 +59,7 @@ Manages individual comment data, including its content, author, and hierarchical **Related Classes/Methods**: -* `QName:`Comment` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py`, Lines:(582:596) `_ +* `Comment:582-596 `_ Redditor ^^^^^^^^ @@ -68,7 +68,7 @@ Provides access to user-specific information, including profile details, submitt **Related Classes/Methods**: -* `QName:`Redditor` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py`, Lines:(810:819) `_ +* `Redditor:810-819 `_ VotableMixin ^^^^^^^^^^^^ @@ -77,7 +77,7 @@ A mixin class that provides common voting functionality (upvote, downvote, clear **Related Classes/Methods**: -* `QName:`VotableMixin` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/votable.py`, Lines:(8:92) `_ +* `VotableMixin:8-92 `_ Modmail ^^^^^^^ @@ -86,7 +86,7 @@ Represents a modmail conversation, facilitating communication between moderators **Related Classes/Methods**: -* `QName:`Modmail` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/subreddit.py`, Lines:(2627:2639) `_ +* `Modmail:2627-2639 `_ LiveThread ^^^^^^^^^^ @@ -95,7 +95,7 @@ Manages data and interactions for Reddit Live Threads, which are real-time, even **Related Classes/Methods**: -* `QName:`LiveThread` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/live.py`, Lines:(261:471) `_ +* `LiveThread:261-471 `_ WikiPage ^^^^^^^^ @@ -104,7 +104,7 @@ Abstracts the content and moderation aspects of a Reddit Wiki Page. It allows fo **Related Classes/Methods**: -* `QName:`WikiPage` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/wikipage.py`, Lines:(146:314) `_ +* `WikiPage:146-314 `_ FAQ diff --git a/.codeboarding/analysis.json b/.codeboarding/analysis.json index c12ed25c3..48c04209f 100644 --- a/.codeboarding/analysis.json +++ b/.codeboarding/analysis.json @@ -143,7 +143,7 @@ "reference_end_line": 189 } ], - "can_expand": false + "can_expand": true } ], "components_relations": [ diff --git a/.codeboarding/codeboarding_version.json b/.codeboarding/codeboarding_version.json index 0a1d38493..f6e5769f9 100644 --- a/.codeboarding/codeboarding_version.json +++ b/.codeboarding/codeboarding_version.json @@ -1,4 +1,4 @@ { - "commit_hash": "3acb442f380f1d496c53de659f5f1a03b633f325", + "commit_hash": "5dcaebd92e024603905c0d8a277ff5568fb44eee", "code_boarding_version": "0.1.0" } diff --git a/.codeboarding/on_boarding.rst b/.codeboarding/overview.rst similarity index 50% rename from .codeboarding/on_boarding.rst rename to .codeboarding/overview.rst index 252f39898..66ccf0d12 100644 --- a/.codeboarding/on_boarding.rst +++ b/.codeboarding/overview.rst @@ -1,5 +1,5 @@ -High-level diagram representation of: praw -========================================== +Overview +======== .. mermaid:: @@ -22,15 +22,16 @@ High-level diagram representation of: praw Listing_Stream_Processors -- "utilizes" --> Reddit_Data_Models Exception_Handling -- "receives errors from" --> API_Client_Core Exception_Handling -- "receives parsed errors from" --> Object_Transformation_Layer - click API_Client_Core href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/API_Client_Core.html" "Details" - click Object_Transformation_Layer href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Object_Transformation_Layer.html" "Details" - click Reddit_Data_Models href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Reddit_Data_Models.html" "Details" - click Listing_Stream_Processors href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Listing_Stream_Processors.html" "Details" + click API_Client_Core href "https://github.com/praw-dev/praw/blob/main/.codeboarding/API_Client_Core.html" "Details" + click Object_Transformation_Layer href "https://github.com/praw-dev/praw/blob/main/.codeboarding/Object_Transformation_Layer.html" "Details" + click Reddit_Data_Models href "https://github.com/praw-dev/praw/blob/main/.codeboarding/Reddit_Data_Models.html" "Details" + click Listing_Stream_Processors href "https://github.com/praw-dev/praw/blob/main/.codeboarding/Listing_Stream_Processors.html" "Details" + click Exception_Handling href "https://github.com/praw-dev/praw/blob/main/.codeboarding/Exception_Handling.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/GeneratedOnBoardings + :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 @@ -50,10 +51,10 @@ The central orchestrator for all interactions with the Reddit API, managing HTTP **Related Classes/Methods**: -* `QName:`praw.reddit.Reddit.__init__` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` `_ -* `QName:`praw.reddit.Reddit.request` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` `_ -* `QName:`praw.reddit.Reddit._objectify_request` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` `_ -* `QName:`praw.reddit.Reddit._handle_rate_limit` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` `_ +* `praw.reddit.Reddit.__init__ `_ +* `praw.reddit.Reddit.request `_ +* `praw.reddit.Reddit._objectify_request `_ +* `praw.reddit.Reddit._handle_rate_limit `_ Configuration Manager ^^^^^^^^^^^^^^^^^^^^^ @@ -62,8 +63,8 @@ Handles the loading, storage, and provision of PRAW's operational settings, incl **Related Classes/Methods**: -* `QName:`praw.config.Config.__init__` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/config.py` `_ -* `QName:`praw.config.Config._load_config` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/config.py` `_ +* `praw.config.Config.__init__ `_ +* `praw.config.Config._load_config `_ Object Transformation Layer ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -74,8 +75,8 @@ Acts as a data mapper, converting raw JSON responses from the Reddit API into ri **Related Classes/Methods**: -* `QName:`praw.objector.Objector.objectify` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py` `_ -* `QName:`praw.objector.Objector.check_error` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py` `_ +* `praw.objector.Objector.objectify `_ +* `praw.objector.Objector.check_error `_ Reddit Data Models ^^^^^^^^^^^^^^^^^^ @@ -86,11 +87,11 @@ A comprehensive set of classes representing various Reddit entities (e.g., `Subr **Related Classes/Methods**: -* `QName:`praw.models.reddit.subreddit.Subreddit.submit` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/subreddit.py` `_ -* `QName:`praw.models.reddit.submission.Submission._fetch_data` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/submission.py` `_ -* `QName:`praw.models.reddit.comment.Comment.parent` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/comment.py` `_ -* `QName:`praw.models.reddit.redditor.Redditor._fetch_info` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/redditor.py` `_ -* `QName:`praw.models.reddit.mixins.votable.VotableMixin._vote` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/votable.py` `_ +* `praw.models.reddit.subreddit.Subreddit.submit `_ +* `praw.models.reddit.submission.Submission._fetch_data `_ +* `praw.models.reddit.comment.Comment.parent `_ +* `praw.models.reddit.redditor.Redditor._fetch_info `_ +* `praw.models.reddit.mixins.votable.VotableMixin._vote `_ Listing & Stream Processors ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -101,18 +102,20 @@ Provides mechanisms for iterating through paginated API responses (listings) and **Related Classes/Methods**: -* `QName:`praw.models.listing.generator.ListingGenerator.__next__` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py` `_ -* `QName:`praw.models.listing.generator.ListingGenerator._next_batch` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py` `_ +* `praw.models.listing.generator.ListingGenerator.__next__ `_ +* `praw.models.listing.generator.ListingGenerator._next_batch `_ Exception Handling ^^^^^^^^^^^^^^^^^^ +:ref:`Expand ` + Defines a hierarchy of custom exception classes specific to PRAW and provides utilities to translate raw API error messages into structured exceptions. **Related Classes/Methods**: -* `QName:`praw.exceptions.PRAWException` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py`, Lines:(14:15) `_ -* `QName:`praw.exceptions.parse_exception_list` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py`, Lines:(173:189) `_ +* `praw.exceptions.PRAWException:14-15 `_ +* `praw.exceptions.parse_exception_list:173-189 `_ FAQ From ca26447b46c4c563b2d18cd0a82f1b18f576dc34 Mon Sep 17 00:00:00 2001 From: ivanmilevtues Date: Mon, 1 Sep 2025 20:50:11 +0200 Subject: [PATCH 08/23] Updates on the github action and adding the results to the docs --- .github/workflows/docs_codeboarding.yml | 28 ++++ .../architecture_overview/API_Client_Core.rst | 115 ++++++++++++++++ .../Exception_Handling.rst | 80 +++++++++++ .../Listing_Stream_Processors.rst | 105 +++++++++++++++ .../Object_Transformation_Layer.rst | 80 +++++++++++ .../Reddit_Data_Models.rst | 113 ++++++++++++++++ docs/architecture_overview/overview.rst | 124 ++++++++++++++++++ docs/conf.py | 1 + docs/index.rst | 13 ++ pyproject.toml | 3 +- 10 files changed, 661 insertions(+), 1 deletion(-) create mode 100644 docs/architecture_overview/API_Client_Core.rst create mode 100644 docs/architecture_overview/Exception_Handling.rst create mode 100644 docs/architecture_overview/Listing_Stream_Processors.rst create mode 100644 docs/architecture_overview/Object_Transformation_Layer.rst create mode 100644 docs/architecture_overview/Reddit_Data_Models.rst create mode 100644 docs/architecture_overview/overview.rst diff --git a/.github/workflows/docs_codeboarding.yml b/.github/workflows/docs_codeboarding.yml index 0e94a301e..1aa8613cf 100644 --- a/.github/workflows/docs_codeboarding.yml +++ b/.github/workflows/docs_codeboarding.yml @@ -87,6 +87,34 @@ jobs: echo "JSON directory: ${{ steps.codeboarding.outputs.json_directory }}" echo "Has changes: ${{ steps.codeboarding.outputs.has_changes }}" + # Move .rst files from docs/architecture_overview/ to .codeboarding folder + - name: Move architecture overview .rst files + run: | + # Create .codeboarding directory if it doesn't exist + mkdir -p .codeboarding + + # Check if docs/architecture_overview/ exists and contains .rst files + if [ -d "docs/architecture_overview" ] && [ -n "$(find docs/architecture_overview -name '*.rst' -type f)" ]; then + echo "Moving .rst files from docs/architecture_overview/ to .codeboarding/" + + # Copy .rst files to .codeboarding folder + cp docs/architecture_overview/*.rst .codeboarding/ 2>/dev/null || echo "No .rst files found to copy" + + # Also copy any subdirectories with .rst files + find docs/architecture_overview -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 .codeboarding/ 2>/dev/null || echo "No .rst files found in $dir" + fi + done + ' sh {} + + + echo "Architecture overview .rst files moved successfully" + else + echo "No docs/architecture_overview/ directory or .rst files found" + fi + # Check if we have any changes to commit - name: Check for changes id: git-changes diff --git a/docs/architecture_overview/API_Client_Core.rst b/docs/architecture_overview/API_Client_Core.rst new file mode 100644 index 000000000..a71c8d5b6 --- /dev/null +++ b/docs/architecture_overview/API_Client_Core.rst @@ -0,0 +1,115 @@ +Api Client Core +=============== + +.. mermaid:: + + graph LR + API_Client_Core["API Client Core"] + Client_Initializer["Client Initializer"] + Request_Executor["Request Executor"] + Response_Objectifier["Response Objectifier"] + Rate_Limit_Manager["Rate Limit Manager"] + API_Operation_Methods["API Operation Methods"] + Async_Checker["Async Checker"] + Client_Initializer -- "initializes" --> API_Client_Core + API_Client_Core -- "manages" --> Request_Executor + API_Client_Core -- "manages" --> Response_Objectifier + API_Client_Core -- "manages" --> Rate_Limit_Manager + API_Client_Core -- "exposes" --> API_Operation_Methods + API_Operation_Methods -- "invokes" --> Request_Executor + Request_Executor -- "checks" --> Async_Checker + Request_Executor -- "returns raw response to" --> Response_Objectifier + Response_Objectifier -- "transforms for" --> API_Operation_Methods + API_Operation_Methods -- "consults" --> Rate_Limit_Manager + click API_Client_Core href "https://github.com/praw-dev/praw/blob/main/.codeboarding/API_Client_Core.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 Reddit API client is structured around the `API Client Core`, which serves as the primary interface for users. This core is set up by the `Client Initializer`, configuring essential components like the HTTP client and response parsing. User interactions, such as fetching data or creating posts, are handled by `API Operation Methods`. These methods delegate the actual HTTP communication to the `Request Executor`, which may consult the `Async Checker` for proper asynchronous execution. Upon receiving a raw response, the `Request Executor` passes it to the `Response Objectifier` for transformation into structured Python objects, which are then returned to the `API Operation Methods`. Throughout this process, the `Rate Limit Manager` is consulted to ensure adherence to Reddit's API usage policies, with the `API Client Core` overseeing and managing these interactions. + +API Client Core +^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +Serves as the main entry point for users to interact with the Reddit API. It orchestrates all underlying operations, manages the client's state, and exposes a high-level, object-oriented interface. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit:57-901 `_ + +Client Initializer +^^^^^^^^^^^^^^^^^^ + +Sets up the API Client Core instance, including configuring the underlying HTTP client (prawcore) and the response objectification mechanism. It integrates `prawcore` for HTTP requests and the `Objector` for response parsing. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit.__init__ `_ +* `praw.reddit._prepare_prawcore:527-546 `_ +* `praw.reddit._prepare_objector:479-525 `_ + +Request Executor +^^^^^^^^^^^^^^^^ + +Executes the raw HTTP requests to the Reddit API, handling the low-level communication details. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit.request `_ + +Response Objectifier +^^^^^^^^^^^^^^^^^^^^ + +Transforms the raw JSON responses from the API into structured PRAW Python objects, making them easier to consume and work with. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit._objectify_request `_ + +Rate Limit Manager +^^^^^^^^^^^^^^^^^^ + +Monitors and enforces Reddit's API rate limits, pausing requests when necessary to prevent exceeding usage quotas and ensuring compliance. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit._handle_rate_limit `_ + +API Operation Methods +^^^^^^^^^^^^^^^^^^^^^ + +Provide specific, high-level methods for common API operations (e.g., fetching data, creating posts, deleting resources), abstracting the underlying request and response handling details from the end-user. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit.get `_ +* `praw.reddit.Reddit.post `_ +* `praw.reddit.Reddit.delete `_ +* `praw.reddit.Reddit.patch `_ +* `praw.reddit.Reddit.put `_ + +Async Checker +^^^^^^^^^^^^^ + +Manages and verifies the asynchronous context for operations, ensuring proper execution in async environments. + +**Related Classes/Methods**: + +* `praw.reddit._check_for_async:388-411 `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/docs/architecture_overview/Exception_Handling.rst b/docs/architecture_overview/Exception_Handling.rst new file mode 100644 index 000000000..847c6a78e --- /dev/null +++ b/docs/architecture_overview/Exception_Handling.rst @@ -0,0 +1,80 @@ +Exception Handling +================== + +.. mermaid:: + + graph LR + ExceptionBase["ExceptionBase"] + ErrorItem["ErrorItem"] + ErrorParser["ErrorParser"] + ErrorDetector["ErrorDetector"] + ExceptionFactory["ExceptionFactory"] + ErrorDetector -- "delegates error parsing to" --> ExceptionFactory + ExceptionFactory -- "converts raw errors to structured items via" --> ErrorParser + ErrorParser -- "creates" --> ErrorItem + ExceptionFactory -- "raises" --> ExceptionBase + +| |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 error handling subsystem efficiently processes raw API responses into structured, actionable exceptions. The `ErrorDetector` initiates the process by identifying potential errors in API responses, subsequently delegating their detailed parsing to the `ExceptionFactory`. The `ExceptionFactory` then leverages the `ErrorParser` to transform raw error data into standardized `ErrorItem` objects. Finally, based on these structured error details, the `ExceptionFactory` constructs and raises appropriate custom exceptions, all derived from the foundational `ExceptionBase`, providing a consistent and predictable error interface for developers. + +ExceptionBase +^^^^^^^^^^^^^ + +The foundational base class for all custom exceptions within PRAW. It establishes a consistent error handling mechanism across the library and provides a unified structure for reporting and handling errors. This is critical for an API wrapper to provide a predictable error interface to developers. + +**Related Classes/Methods**: + +* `praw.exceptions.PRAWException:14-15 `_ + +ErrorItem +^^^^^^^^^ + +A data structure that encapsulates the details of a single, specific error returned by the Reddit API. It provides a standardized and easily accessible format for error information, transforming raw API responses into structured, consumable objects. This component is vital for abstracting raw API error messages into a developer-friendly format. + +**Related Classes/Methods**: + +* `praw.exceptions.RedditErrorItem:18-71 `_ + +ErrorParser +^^^^^^^^^^^ + +A crucial utility function responsible for transforming raw, unstructured error data received from the Reddit API into a list of structured `ErrorItem` objects. It acts as a parser, converting raw error dictionaries into `praw.exceptions.RedditErrorItem` instances, which is essential for making API errors manageable. + +**Related Classes/Methods**: + +* `praw.exceptions.parse_exception_list:173-189 `_ + +ErrorDetector +^^^^^^^^^^^^^ + +The initial entry point for error detection within API responses. It acts as a preliminary gatekeeper that identifies potential errors in the raw API response and delegates further processing. This component is the first line of defense in the error handling pipeline, ensuring that only responses with potential errors are further processed. + +**Related Classes/Methods**: + +* `praw.objector.check_error:20-24 `_ + +ExceptionFactory +^^^^^^^^^^^^^^^^ + +The core orchestrator for converting raw API error structures into PRAW-specific exception objects. It manages the flow from raw error data to structured exceptions, acting as an adapter between the raw API error format and PRAW's internal exception system. This component is central to raising appropriate, custom exceptions for the API wrapper. + +**Related Classes/Methods**: + +* `praw.objector.parse_error:26-48 `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/docs/architecture_overview/Listing_Stream_Processors.rst b/docs/architecture_overview/Listing_Stream_Processors.rst new file mode 100644 index 000000000..ec5a2a4fa --- /dev/null +++ b/docs/architecture_overview/Listing_Stream_Processors.rst @@ -0,0 +1,105 @@ +Listing Stream Processors +========================= + +.. mermaid:: + + graph LR + ListingGenerator["ListingGenerator"] + ListingBatchFetcher["ListingBatchFetcher"] + ListingDataExtractor["ListingDataExtractor"] + ListingParameterMixin["ListingParameterMixin"] + StreamProcessor["StreamProcessor"] + StreamUniquenessManager["StreamUniquenessManager"] + StreamBackoffHandler["StreamBackoffHandler"] + ListingGenerator -- "initiates data retrieval by calling" --> ListingBatchFetcher + ListingBatchFetcher -- "fetches data and returns it to" --> ListingGenerator + ListingBatchFetcher -- "invokes" --> ListingDataExtractor + ListingDataExtractor -- "provides the extracted list of items back to" --> ListingBatchFetcher + ListingParameterMixin -- "is utilized by" --> ListingBatchFetcher + StreamProcessor -- "utilizes" --> StreamUniquenessManager + StreamUniquenessManager -- "provides uniqueness checks for" --> StreamProcessor + StreamProcessor -- "consults" --> StreamBackoffHandler + StreamBackoffHandler -- "provides backoff durations to" --> StreamProcessor + +| |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 +------- + +This subsystem is responsible for abstracting the complexities of consuming data from the Reddit API, specifically handling paginated "listings" (e.g., posts in a subreddit) and continuous "streams" of new data (e.g., new comments). It ensures efficient data retrieval, manages pagination state, handles item uniqueness in streams, and implements robust backoff strategies to respect API rate limits. + +ListingGenerator +^^^^^^^^^^^^^^^^ + +Provides an iterable interface for consuming paginated API responses. It manages the state of pagination, such as the `_after` parameter, to fetch subsequent batches of data seamlessly. + +**Related Classes/Methods**: + +* `ListingGenerator:17-103 `_ + +ListingBatchFetcher +^^^^^^^^^^^^^^^^^^^ + +Responsible for fetching a single batch of items from the Reddit API using the underlying `Reddit` client. It utilizes the pagination state provided by `ListingGenerator` to request the correct segment of data. + +**Related Classes/Methods**: + +* `ListingBatchFetcher:1-1000 `_ + +ListingDataExtractor +^^^^^^^^^^^^^^^^^^^^ + +Parses the raw JSON response received from the API, isolating and returning the actual list of data objects (e.g., posts, comments) from the API's wrapper structure. + +**Related Classes/Methods**: + +* `ListingDataExtractor:1-1000 `_ + +ListingParameterMixin +^^^^^^^^^^^^^^^^^^^^^ + +Provides common methods for constructing API paths and parameters required for various types of listings. This ensures consistency and reusability across different listing endpoints. + +**Related Classes/Methods**: + +* `ListingParameterMixin:1-1000 `_ + +StreamProcessor +^^^^^^^^^^^^^^^ + +Implements the foundational logic for consuming continuous data streams from the Reddit API. It manages the overall flow, including delays between requests and ensuring resilient fetching. + +**Related Classes/Methods**: + +* `StreamProcessor:1-1000 `_ + +StreamUniquenessManager +^^^^^^^^^^^^^^^^^^^^^^^ + +Maintains a limited set of recently seen items to ensure uniqueness within a data stream. This prevents reprocessing of duplicate items, which is crucial for real-time data consumption. + +**Related Classes/Methods**: + +* `StreamUniquenessManager:1-1000 `_ + +StreamBackoffHandler +^^^^^^^^^^^^^^^^^^^^ + +Implements an exponential backoff strategy to manage delays between stream requests. This is critical for respecting API rate limits and preventing excessive requests that could lead to temporary bans. + +**Related Classes/Methods**: + +* `StreamBackoffHandler:1-1000 `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/docs/architecture_overview/Object_Transformation_Layer.rst b/docs/architecture_overview/Object_Transformation_Layer.rst new file mode 100644 index 000000000..2fccb831b --- /dev/null +++ b/docs/architecture_overview/Object_Transformation_Layer.rst @@ -0,0 +1,80 @@ +Object Transformation Layer +=========================== + +.. mermaid:: + + graph LR + praw_objector_Objector["praw.objector.Objector"] + praw_objector_Objector_objectify["praw.objector.Objector:objectify"] + praw_objector_Objector__objectify_dict["praw.objector.Objector:_objectify_dict"] + praw_objector_Objector_check_error["praw.objector.Objector:check_error"] + praw_objector_Objector_parse_error["praw.objector.Objector:parse_error"] + praw_objector_Objector -- "invokes" --> praw_objector_Objector_objectify + praw_objector_Objector -- "invokes" --> praw_objector_Objector_check_error + praw_objector_Objector_objectify -- "utilizes" --> praw_objector_Objector__objectify_dict + praw_objector_Objector_check_error -- "delegates to" --> praw_objector_Objector_parse_error + +| |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.objector` subsystem is designed to seamlessly convert raw data from the Reddit API into usable PRAW objects while providing robust error handling. The `Objector` class serves as the central entry point, orchestrating the objectification and error-checking processes. The `objectify` method, with the assistance of `_objectify_dict`, recursively transforms complex data structures into their corresponding PRAW object representations. Concurrently, the `check_error` method, by delegating to `parse_error`, ensures that any API-reported errors are properly identified and converted into structured exceptions, maintaining the integrity and reliability of the data processing pipeline. This clear separation of concerns between data transformation and error management allows for a modular and maintainable architecture. + +praw.objector.Objector +^^^^^^^^^^^^^^^^^^^^^^ + +The central orchestrator of the transformation process, converting raw JSON responses into structured Python objects and managing error detection. It acts as the primary interface for the objectification process. + +**Related Classes/Methods**: + +* `praw.objector.Objector:17-263 `_ + +praw.objector.Objector:objectify +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Implements the core recursive logic for data transformation, traversing raw JSON data, identifying appropriate PRAW object types, and instantiating them. This method is the heart of the data mapping functionality. + +**Related Classes/Methods**: + +* `praw.objector.Objector:objectify:199-279 `_ + +praw.objector.Objector:_objectify_dict +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A specialized helper method for `objectify`, focusing on converting individual dictionary elements within the raw data into their corresponding PRAW object representations. It handles the granular conversion of data structures. + +**Related Classes/Methods**: + +* `praw.objector.Objector:_objectify_dict:46-197 `_ + +praw.objector.Objector:check_error +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Responsible for scanning API responses for error indicators and delegating to `parse_error` if an error is detected. This ensures robust error handling within the transformation pipeline. + +**Related Classes/Methods**: + +* `praw.objector.Objector:check_error:6-11 `_ + +praw.objector.Objector:parse_error +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Interprets raw error data from the API response, converting it into a structured format or raising a specific exception relevant to the PRAW library. This component standardizes error reporting. + +**Related Classes/Methods**: + +* `praw.objector.Objector:parse_error:13-44 `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/docs/architecture_overview/Reddit_Data_Models.rst b/docs/architecture_overview/Reddit_Data_Models.rst new file mode 100644 index 000000000..d6e6f9d3a --- /dev/null +++ b/docs/architecture_overview/Reddit_Data_Models.rst @@ -0,0 +1,113 @@ +Reddit Data Models +================== + +.. mermaid:: + + graph LR + Subreddit["Subreddit"] + Submission["Submission"] + Comment["Comment"] + Redditor["Redditor"] + VotableMixin["VotableMixin"] + Modmail["Modmail"] + LiveThread["LiveThread"] + WikiPage["WikiPage"] + Subreddit -- "creates and fetches" --> Submission + Subreddit -- "composes" --> Modmail + Submission -- "retrieves and references" --> Comment + Submission -- "inherits from" --> VotableMixin + Comment -- "inherits from" --> VotableMixin + Modmail -- "involves" --> Redditor + WikiPage -- "associated with" --> Subreddit + +| |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 for interacting with Reddit content is centered around key models representing Reddit entities. The Subreddit component acts as a central hub for community-specific interactions, enabling the creation and retrieval of Submission objects. Submission objects, in turn, manage post data and facilitate interactions with Comment threads. Both Submission and Comment leverage the VotableMixin for consistent voting functionality, demonstrating effective code reuse through inheritance. User-centric operations are handled by the Redditor component, which is involved in Modmail conversations. Modmail itself is composed by Subreddit, indicating its role in community moderation. LiveThread and WikiPage represent distinct content streams and informational pages, with WikiPage being directly associated with a Subreddit. This design emphasizes a clear separation of concerns, with each component encapsulating specific Reddit functionality and interacting through well-defined relationships to manage and present Reddit data. + +Subreddit +^^^^^^^^^ + +Manages subreddit data, submissions, moderation, flair, and style. It acts as a primary facade for subreddit-specific API calls, allowing users to interact with a community's content and settings. + +**Related Classes/Methods**: + +* `praw.models.reddit.subreddit.Subreddit `_ + +Submission +^^^^^^^^^^ + +Encapsulates Reddit post data, including content, flair, and moderation status. It provides methods for retrieving content and interacting with the post (e.g., voting, commenting). + +**Related Classes/Methods**: + +* `praw.models.reddit.submission.Submission `_ + +Comment +^^^^^^^ + +Manages individual comment data, including its content, author, and hierarchical position within a discussion. It provides methods for moderation and navigating comment threads. + +**Related Classes/Methods**: + +* `Comment:582-596 `_ + +Redditor +^^^^^^^^ + +Provides access to user-specific information, including profile details, submitted content, and comments. It enables interactions related to a specific Reddit user. + +**Related Classes/Methods**: + +* `Redditor:810-819 `_ + +VotableMixin +^^^^^^^^^^^^ + +A mixin class that provides common voting functionality (upvote, downvote, clear vote) to any Reddit entity that can be voted on. This promotes code reuse and consistency across votable models. + +**Related Classes/Methods**: + +* `VotableMixin:8-92 `_ + +Modmail +^^^^^^^ + +Represents a modmail conversation, facilitating communication between moderators and users, or between moderators themselves. It encapsulates messages and conversation states. + +**Related Classes/Methods**: + +* `Modmail:2627-2639 `_ + +LiveThread +^^^^^^^^^^ + +Manages data and interactions for Reddit Live Threads, which are real-time, event-driven content streams. It provides access to updates and thread metadata. + +**Related Classes/Methods**: + +* `LiveThread:261-471 `_ + +WikiPage +^^^^^^^^ + +Abstracts the content and moderation aspects of a Reddit Wiki Page. It allows for retrieval, editing, and management of wiki content within a subreddit. + +**Related Classes/Methods**: + +* `WikiPage:146-314 `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/docs/architecture_overview/overview.rst b/docs/architecture_overview/overview.rst new file mode 100644 index 000000000..66ccf0d12 --- /dev/null +++ b/docs/architecture_overview/overview.rst @@ -0,0 +1,124 @@ +Overview +======== + +.. mermaid:: + + graph LR + API_Client_Core["API Client Core"] + Configuration_Manager["Configuration Manager"] + Object_Transformation_Layer["Object Transformation Layer"] + Reddit_Data_Models["Reddit Data Models"] + Listing_Stream_Processors["Listing & Stream Processors"] + Exception_Handling["Exception Handling"] + API_Client_Core -- "uses" --> Configuration_Manager + API_Client_Core -- "sends raw responses to" --> Object_Transformation_Layer + API_Client_Core -- "reports errors to" --> Exception_Handling + Object_Transformation_Layer -- "receives raw responses from" --> API_Client_Core + Object_Transformation_Layer -- "instantiates" --> Reddit_Data_Models + Object_Transformation_Layer -- "parses errors with" --> Exception_Handling + Reddit_Data_Models -- "initiates requests via" --> API_Client_Core + Reddit_Data_Models -- "are utilized by" --> Listing_Stream_Processors + Listing_Stream_Processors -- "fetches batches via" --> API_Client_Core + Listing_Stream_Processors -- "utilizes" --> Reddit_Data_Models + Exception_Handling -- "receives errors from" --> API_Client_Core + Exception_Handling -- "receives parsed errors from" --> Object_Transformation_Layer + click API_Client_Core href "https://github.com/praw-dev/praw/blob/main/.codeboarding/API_Client_Core.html" "Details" + click Object_Transformation_Layer href "https://github.com/praw-dev/praw/blob/main/.codeboarding/Object_Transformation_Layer.html" "Details" + click Reddit_Data_Models href "https://github.com/praw-dev/praw/blob/main/.codeboarding/Reddit_Data_Models.html" "Details" + click Listing_Stream_Processors href "https://github.com/praw-dev/praw/blob/main/.codeboarding/Listing_Stream_Processors.html" "Details" + click Exception_Handling href "https://github.com/praw-dev/praw/blob/main/.codeboarding/Exception_Handling.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 architecture is designed as a robust API wrapper, providing an object-oriented interface to the Reddit API. It centers around the `API Client Core`, which orchestrates all network interactions, leveraging the `Configuration Manager` for settings and delegating raw response processing to the `Object Transformation Layer`. This layer is responsible for mapping raw API data into rich `Reddit Data Models`, which encapsulate Reddit entities and their behaviors. For handling collections and real-time data, the `Listing & Stream Processors` work in conjunction with the `API Client Core` and `Reddit Data Models`. Critical to its reliability, the `Exception Handling` component provides structured error reporting across the system. This design ensures a clear separation of concerns, facilitating maintainability, extensibility, and a developer-friendly experience, making it ideal for both documentation and visual flow graph representation. + +API Client Core +^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +The central orchestrator for all interactions with the Reddit API, managing HTTP requests, authentication, and rate limiting. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit.__init__ `_ +* `praw.reddit.Reddit.request `_ +* `praw.reddit.Reddit._objectify_request `_ +* `praw.reddit.Reddit._handle_rate_limit `_ + +Configuration Manager +^^^^^^^^^^^^^^^^^^^^^ + +Handles the loading, storage, and provision of PRAW's operational settings, including API credentials and user agent strings. + +**Related Classes/Methods**: + +* `praw.config.Config.__init__ `_ +* `praw.config.Config._load_config `_ + +Object Transformation Layer +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +Acts as a data mapper, converting raw JSON responses from the Reddit API into rich, object-oriented Python representations (`Reddit Data Models`). + +**Related Classes/Methods**: + +* `praw.objector.Objector.objectify `_ +* `praw.objector.Objector.check_error `_ + +Reddit Data Models +^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +A comprehensive set of classes representing various Reddit entities (e.g., `Subreddit`, `Submission`, `Comment`, `Redditor`). These models encapsulate data and provide high-level methods for interacting with their respective API endpoints. + +**Related Classes/Methods**: + +* `praw.models.reddit.subreddit.Subreddit.submit `_ +* `praw.models.reddit.submission.Submission._fetch_data `_ +* `praw.models.reddit.comment.Comment.parent `_ +* `praw.models.reddit.redditor.Redditor._fetch_info `_ +* `praw.models.reddit.mixins.votable.VotableMixin._vote `_ + +Listing & Stream Processors +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +Provides mechanisms for iterating through paginated API responses (listings) and consuming real-time data streams from Reddit, handling pagination logic and item uniqueness. + +**Related Classes/Methods**: + +* `praw.models.listing.generator.ListingGenerator.__next__ `_ +* `praw.models.listing.generator.ListingGenerator._next_batch `_ + +Exception Handling +^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +Defines a hierarchy of custom exception classes specific to PRAW and provides utilities to translate raw API error messages into structured exceptions. + +**Related Classes/Methods**: + +* `praw.exceptions.PRAWException:14-15 `_ +* `praw.exceptions.parse_exception_list:173-189 `_ + + +FAQ +--- + +`See the FAQ `_ 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..8e974e9c0 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,18 @@ 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/API_Client_Core + architecture_overview/Object_Transformation_Layer + architecture_overview/Reddit_Data_Models + architecture_overview/Listing_Stream_Processors + .. _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", From 77a7068260724ac0c39edf4c7d72b424873cc1d0 Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Mon, 1 Sep 2025 18:52:13 +0000 Subject: [PATCH 09/23] docs: update codeboarding documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 📚 Documentation Update This commit contains updated documentation files fetched from the CodeBoarding service. ### 📊 Summary - Documentation files created/updated: 5 - JSON files created/updated: 6 - Documentation directory: .codeboarding/ - JSON directory: .codeboarding/ - Output format: .rst - Repository analyzed: https://github.com/CodeBoarding/praw - Source branch: main - Target branch: main 🤖 This commit was automatically generated by the CodeBoarding documentation update workflow. --- .codeboarding/Exception_Handling.json | 92 ------------------------- .codeboarding/analysis.json | 2 +- .codeboarding/codeboarding_version.json | 2 +- 3 files changed, 2 insertions(+), 94 deletions(-) delete mode 100644 .codeboarding/Exception_Handling.json diff --git a/.codeboarding/Exception_Handling.json b/.codeboarding/Exception_Handling.json deleted file mode 100644 index dbef45d40..000000000 --- a/.codeboarding/Exception_Handling.json +++ /dev/null @@ -1,92 +0,0 @@ -{ - "description": "The PRAW error handling subsystem efficiently processes raw API responses into structured, actionable exceptions. The `ErrorDetector` initiates the process by identifying potential errors in API responses, subsequently delegating their detailed parsing to the `ExceptionFactory`. The `ExceptionFactory` then leverages the `ErrorParser` to transform raw error data into standardized `ErrorItem` objects. Finally, based on these structured error details, the `ExceptionFactory` constructs and raises appropriate custom exceptions, all derived from the foundational `ExceptionBase`, providing a consistent and predictable error interface for developers.", - "components": [ - { - "name": "ExceptionBase", - "description": "The foundational base class for all custom exceptions within PRAW. It establishes a consistent error handling mechanism across the library and provides a unified structure for reporting and handling errors. This is critical for an API wrapper to provide a predictable error interface to developers.", - "referenced_source_code": [ - { - "qualified_name": "praw.exceptions.PRAWException", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py", - "reference_start_line": 14, - "reference_end_line": 15 - } - ], - "can_expand": false - }, - { - "name": "ErrorItem", - "description": "A data structure that encapsulates the details of a single, specific error returned by the Reddit API. It provides a standardized and easily accessible format for error information, transforming raw API responses into structured, consumable objects. This component is vital for abstracting raw API error messages into a developer-friendly format.", - "referenced_source_code": [ - { - "qualified_name": "praw.exceptions.RedditErrorItem", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py", - "reference_start_line": 18, - "reference_end_line": 71 - } - ], - "can_expand": false - }, - { - "name": "ErrorParser", - "description": "A crucial utility function responsible for transforming raw, unstructured error data received from the Reddit API into a list of structured `ErrorItem` objects. It acts as a parser, converting raw error dictionaries into `praw.exceptions.RedditErrorItem` instances, which is essential for making API errors manageable.", - "referenced_source_code": [ - { - "qualified_name": "praw.exceptions.parse_exception_list", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py", - "reference_start_line": 173, - "reference_end_line": 189 - } - ], - "can_expand": false - }, - { - "name": "ErrorDetector", - "description": "The initial entry point for error detection within API responses. It acts as a preliminary gatekeeper that identifies potential errors in the raw API response and delegates further processing. This component is the first line of defense in the error handling pipeline, ensuring that only responses with potential errors are further processed.", - "referenced_source_code": [ - { - "qualified_name": "praw.objector.check_error", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py", - "reference_start_line": 20, - "reference_end_line": 24 - } - ], - "can_expand": false - }, - { - "name": "ExceptionFactory", - "description": "The core orchestrator for converting raw API error structures into PRAW-specific exception objects. It manages the flow from raw error data to structured exceptions, acting as an adapter between the raw API error format and PRAW's internal exception system. This component is central to raising appropriate, custom exceptions for the API wrapper.", - "referenced_source_code": [ - { - "qualified_name": "praw.objector.parse_error", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py", - "reference_start_line": 26, - "reference_end_line": 48 - } - ], - "can_expand": true - } - ], - "components_relations": [ - { - "relation": "delegates error parsing to", - "src_name": "ErrorDetector", - "dst_name": "ExceptionFactory" - }, - { - "relation": "converts raw errors to structured items via", - "src_name": "ExceptionFactory", - "dst_name": "ErrorParser" - }, - { - "relation": "creates", - "src_name": "ErrorParser", - "dst_name": "ErrorItem" - }, - { - "relation": "raises", - "src_name": "ExceptionFactory", - "dst_name": "ExceptionBase" - } - ] -} diff --git a/.codeboarding/analysis.json b/.codeboarding/analysis.json index 48c04209f..c12ed25c3 100644 --- a/.codeboarding/analysis.json +++ b/.codeboarding/analysis.json @@ -143,7 +143,7 @@ "reference_end_line": 189 } ], - "can_expand": true + "can_expand": false } ], "components_relations": [ diff --git a/.codeboarding/codeboarding_version.json b/.codeboarding/codeboarding_version.json index f6e5769f9..5bb933317 100644 --- a/.codeboarding/codeboarding_version.json +++ b/.codeboarding/codeboarding_version.json @@ -1,4 +1,4 @@ { - "commit_hash": "5dcaebd92e024603905c0d8a277ff5568fb44eee", + "commit_hash": "ca26447b46c4c563b2d18cd0a82f1b18f576dc34", "code_boarding_version": "0.1.0" } From 3a1249a579ce1b58816a4e74ae7ffa22e28042ae Mon Sep 17 00:00:00 2001 From: ivanmilevtues Date: Mon, 1 Sep 2025 20:53:47 +0200 Subject: [PATCH 10/23] Removed files for fresh run --- .codeboarding/API_Client_Core.json | 177 --------------- .codeboarding/API_Client_Core.rst | 115 ---------- .codeboarding/Exception_Handling.rst | 80 ------- .codeboarding/Listing_Stream_Processors.json | 136 ----------- .codeboarding/Listing_Stream_Processors.rst | 105 --------- .../Object_Transformation_Layer.json | 87 -------- .codeboarding/Object_Transformation_Layer.rst | 80 ------- .codeboarding/Reddit_Data_Models.json | 138 ------------ .codeboarding/Reddit_Data_Models.rst | 113 ---------- .codeboarding/analysis.json | 211 ------------------ .codeboarding/codeboarding_version.json | 4 - .codeboarding/overview.rst | 124 ---------- .../architecture_overview/API_Client_Core.rst | 115 ---------- .../Exception_Handling.rst | 80 ------- .../Listing_Stream_Processors.rst | 105 --------- .../Object_Transformation_Layer.rst | 80 ------- .../Reddit_Data_Models.rst | 113 ---------- docs/architecture_overview/overview.rst | 124 ---------- 18 files changed, 1987 deletions(-) delete mode 100644 .codeboarding/API_Client_Core.json delete mode 100644 .codeboarding/API_Client_Core.rst delete mode 100644 .codeboarding/Exception_Handling.rst delete mode 100644 .codeboarding/Listing_Stream_Processors.json delete mode 100644 .codeboarding/Listing_Stream_Processors.rst delete mode 100644 .codeboarding/Object_Transformation_Layer.json delete mode 100644 .codeboarding/Object_Transformation_Layer.rst delete mode 100644 .codeboarding/Reddit_Data_Models.json delete mode 100644 .codeboarding/Reddit_Data_Models.rst delete mode 100644 .codeboarding/analysis.json delete mode 100644 .codeboarding/codeboarding_version.json delete mode 100644 .codeboarding/overview.rst delete mode 100644 docs/architecture_overview/API_Client_Core.rst delete mode 100644 docs/architecture_overview/Exception_Handling.rst delete mode 100644 docs/architecture_overview/Listing_Stream_Processors.rst delete mode 100644 docs/architecture_overview/Object_Transformation_Layer.rst delete mode 100644 docs/architecture_overview/Reddit_Data_Models.rst delete mode 100644 docs/architecture_overview/overview.rst diff --git a/.codeboarding/API_Client_Core.json b/.codeboarding/API_Client_Core.json deleted file mode 100644 index 33eab5c8a..000000000 --- a/.codeboarding/API_Client_Core.json +++ /dev/null @@ -1,177 +0,0 @@ -{ - "description": "The PRAW Reddit API client is structured around the `API Client Core`, which serves as the primary interface for users. This core is set up by the `Client Initializer`, configuring essential components like the HTTP client and response parsing. User interactions, such as fetching data or creating posts, are handled by `API Operation Methods`. These methods delegate the actual HTTP communication to the `Request Executor`, which may consult the `Async Checker` for proper asynchronous execution. Upon receiving a raw response, the `Request Executor` passes it to the `Response Objectifier` for transformation into structured Python objects, which are then returned to the `API Operation Methods`. Throughout this process, the `Rate Limit Manager` is consulted to ensure adherence to Reddit's API usage policies, with the `API Client Core` overseeing and managing these interactions.", - "components": [ - { - "name": "API Client Core", - "description": "Serves as the main entry point for users to interact with the Reddit API. It orchestrates all underlying operations, manages the client's state, and exposes a high-level, object-oriented interface.", - "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": "Client Initializer", - "description": "Sets up the API Client Core instance, including configuring the underlying HTTP client (prawcore) and the response objectification mechanism. It integrates `prawcore` for HTTP requests and the `Objector` for response parsing.", - "referenced_source_code": [ - { - "qualified_name": "praw.reddit.Reddit.__init__", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", - "reference_start_line": 0, - "reference_end_line": 0 - }, - { - "qualified_name": "praw.reddit._prepare_prawcore", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", - "reference_start_line": 527, - "reference_end_line": 546 - }, - { - "qualified_name": "praw.reddit._prepare_objector", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", - "reference_start_line": 479, - "reference_end_line": 525 - } - ] - }, - { - "name": "Request Executor", - "description": "Executes the raw HTTP requests to the Reddit API, handling the low-level communication details.", - "referenced_source_code": [ - { - "qualified_name": "praw.reddit.Reddit.request", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", - "reference_start_line": 0, - "reference_end_line": 0 - } - ] - }, - { - "name": "Response Objectifier", - "description": "Transforms the raw JSON responses from the API into structured PRAW Python objects, making them easier to consume and work with.", - "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 - } - ] - }, - { - "name": "Rate Limit Manager", - "description": "Monitors and enforces Reddit's API rate limits, pausing requests when necessary to prevent exceeding usage quotas and ensuring compliance.", - "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 - } - ] - }, - { - "name": "API Operation Methods", - "description": "Provide specific, high-level methods for common API operations (e.g., fetching data, creating posts, deleting resources), abstracting the underlying request and response handling details from the end-user.", - "referenced_source_code": [ - { - "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.post", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", - "reference_start_line": 0, - "reference_end_line": 0 - }, - { - "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.patch", - "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 - } - ] - }, - { - "name": "Async Checker", - "description": "Manages and verifies the asynchronous context for operations, ensuring proper execution in async environments.", - "referenced_source_code": [ - { - "qualified_name": "praw.reddit._check_for_async", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", - "reference_start_line": 388, - "reference_end_line": 411 - } - ] - } - ], - "components_relations": [ - { - "relation": "initializes", - "src_name": "Client Initializer", - "dst_name": "API Client Core" - }, - { - "relation": "manages", - "src_name": "API Client Core", - "dst_name": "Request Executor" - }, - { - "relation": "manages", - "src_name": "API Client Core", - "dst_name": "Response Objectifier" - }, - { - "relation": "manages", - "src_name": "API Client Core", - "dst_name": "Rate Limit Manager" - }, - { - "relation": "exposes", - "src_name": "API Client Core", - "dst_name": "API Operation Methods" - }, - { - "relation": "invokes", - "src_name": "API Operation Methods", - "dst_name": "Request Executor" - }, - { - "relation": "checks", - "src_name": "Request Executor", - "dst_name": "Async Checker" - }, - { - "relation": "returns raw response to", - "src_name": "Request Executor", - "dst_name": "Response Objectifier" - }, - { - "relation": "transforms for", - "src_name": "Response Objectifier", - "dst_name": "API Operation Methods" - }, - { - "relation": "consults", - "src_name": "API Operation Methods", - "dst_name": "Rate Limit Manager" - } - ] -} diff --git a/.codeboarding/API_Client_Core.rst b/.codeboarding/API_Client_Core.rst deleted file mode 100644 index a71c8d5b6..000000000 --- a/.codeboarding/API_Client_Core.rst +++ /dev/null @@ -1,115 +0,0 @@ -Api Client Core -=============== - -.. mermaid:: - - graph LR - API_Client_Core["API Client Core"] - Client_Initializer["Client Initializer"] - Request_Executor["Request Executor"] - Response_Objectifier["Response Objectifier"] - Rate_Limit_Manager["Rate Limit Manager"] - API_Operation_Methods["API Operation Methods"] - Async_Checker["Async Checker"] - Client_Initializer -- "initializes" --> API_Client_Core - API_Client_Core -- "manages" --> Request_Executor - API_Client_Core -- "manages" --> Response_Objectifier - API_Client_Core -- "manages" --> Rate_Limit_Manager - API_Client_Core -- "exposes" --> API_Operation_Methods - API_Operation_Methods -- "invokes" --> Request_Executor - Request_Executor -- "checks" --> Async_Checker - Request_Executor -- "returns raw response to" --> Response_Objectifier - Response_Objectifier -- "transforms for" --> API_Operation_Methods - API_Operation_Methods -- "consults" --> Rate_Limit_Manager - click API_Client_Core href "https://github.com/praw-dev/praw/blob/main/.codeboarding/API_Client_Core.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 Reddit API client is structured around the `API Client Core`, which serves as the primary interface for users. This core is set up by the `Client Initializer`, configuring essential components like the HTTP client and response parsing. User interactions, such as fetching data or creating posts, are handled by `API Operation Methods`. These methods delegate the actual HTTP communication to the `Request Executor`, which may consult the `Async Checker` for proper asynchronous execution. Upon receiving a raw response, the `Request Executor` passes it to the `Response Objectifier` for transformation into structured Python objects, which are then returned to the `API Operation Methods`. Throughout this process, the `Rate Limit Manager` is consulted to ensure adherence to Reddit's API usage policies, with the `API Client Core` overseeing and managing these interactions. - -API Client Core -^^^^^^^^^^^^^^^ - -:ref:`Expand ` - -Serves as the main entry point for users to interact with the Reddit API. It orchestrates all underlying operations, manages the client's state, and exposes a high-level, object-oriented interface. - -**Related Classes/Methods**: - -* `praw.reddit.Reddit:57-901 `_ - -Client Initializer -^^^^^^^^^^^^^^^^^^ - -Sets up the API Client Core instance, including configuring the underlying HTTP client (prawcore) and the response objectification mechanism. It integrates `prawcore` for HTTP requests and the `Objector` for response parsing. - -**Related Classes/Methods**: - -* `praw.reddit.Reddit.__init__ `_ -* `praw.reddit._prepare_prawcore:527-546 `_ -* `praw.reddit._prepare_objector:479-525 `_ - -Request Executor -^^^^^^^^^^^^^^^^ - -Executes the raw HTTP requests to the Reddit API, handling the low-level communication details. - -**Related Classes/Methods**: - -* `praw.reddit.Reddit.request `_ - -Response Objectifier -^^^^^^^^^^^^^^^^^^^^ - -Transforms the raw JSON responses from the API into structured PRAW Python objects, making them easier to consume and work with. - -**Related Classes/Methods**: - -* `praw.reddit.Reddit._objectify_request `_ - -Rate Limit Manager -^^^^^^^^^^^^^^^^^^ - -Monitors and enforces Reddit's API rate limits, pausing requests when necessary to prevent exceeding usage quotas and ensuring compliance. - -**Related Classes/Methods**: - -* `praw.reddit.Reddit._handle_rate_limit `_ - -API Operation Methods -^^^^^^^^^^^^^^^^^^^^^ - -Provide specific, high-level methods for common API operations (e.g., fetching data, creating posts, deleting resources), abstracting the underlying request and response handling details from the end-user. - -**Related Classes/Methods**: - -* `praw.reddit.Reddit.get `_ -* `praw.reddit.Reddit.post `_ -* `praw.reddit.Reddit.delete `_ -* `praw.reddit.Reddit.patch `_ -* `praw.reddit.Reddit.put `_ - -Async Checker -^^^^^^^^^^^^^ - -Manages and verifies the asynchronous context for operations, ensuring proper execution in async environments. - -**Related Classes/Methods**: - -* `praw.reddit._check_for_async:388-411 `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/.codeboarding/Exception_Handling.rst b/.codeboarding/Exception_Handling.rst deleted file mode 100644 index 847c6a78e..000000000 --- a/.codeboarding/Exception_Handling.rst +++ /dev/null @@ -1,80 +0,0 @@ -Exception Handling -================== - -.. mermaid:: - - graph LR - ExceptionBase["ExceptionBase"] - ErrorItem["ErrorItem"] - ErrorParser["ErrorParser"] - ErrorDetector["ErrorDetector"] - ExceptionFactory["ExceptionFactory"] - ErrorDetector -- "delegates error parsing to" --> ExceptionFactory - ExceptionFactory -- "converts raw errors to structured items via" --> ErrorParser - ErrorParser -- "creates" --> ErrorItem - ExceptionFactory -- "raises" --> ExceptionBase - -| |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 error handling subsystem efficiently processes raw API responses into structured, actionable exceptions. The `ErrorDetector` initiates the process by identifying potential errors in API responses, subsequently delegating their detailed parsing to the `ExceptionFactory`. The `ExceptionFactory` then leverages the `ErrorParser` to transform raw error data into standardized `ErrorItem` objects. Finally, based on these structured error details, the `ExceptionFactory` constructs and raises appropriate custom exceptions, all derived from the foundational `ExceptionBase`, providing a consistent and predictable error interface for developers. - -ExceptionBase -^^^^^^^^^^^^^ - -The foundational base class for all custom exceptions within PRAW. It establishes a consistent error handling mechanism across the library and provides a unified structure for reporting and handling errors. This is critical for an API wrapper to provide a predictable error interface to developers. - -**Related Classes/Methods**: - -* `praw.exceptions.PRAWException:14-15 `_ - -ErrorItem -^^^^^^^^^ - -A data structure that encapsulates the details of a single, specific error returned by the Reddit API. It provides a standardized and easily accessible format for error information, transforming raw API responses into structured, consumable objects. This component is vital for abstracting raw API error messages into a developer-friendly format. - -**Related Classes/Methods**: - -* `praw.exceptions.RedditErrorItem:18-71 `_ - -ErrorParser -^^^^^^^^^^^ - -A crucial utility function responsible for transforming raw, unstructured error data received from the Reddit API into a list of structured `ErrorItem` objects. It acts as a parser, converting raw error dictionaries into `praw.exceptions.RedditErrorItem` instances, which is essential for making API errors manageable. - -**Related Classes/Methods**: - -* `praw.exceptions.parse_exception_list:173-189 `_ - -ErrorDetector -^^^^^^^^^^^^^ - -The initial entry point for error detection within API responses. It acts as a preliminary gatekeeper that identifies potential errors in the raw API response and delegates further processing. This component is the first line of defense in the error handling pipeline, ensuring that only responses with potential errors are further processed. - -**Related Classes/Methods**: - -* `praw.objector.check_error:20-24 `_ - -ExceptionFactory -^^^^^^^^^^^^^^^^ - -The core orchestrator for converting raw API error structures into PRAW-specific exception objects. It manages the flow from raw error data to structured exceptions, acting as an adapter between the raw API error format and PRAW's internal exception system. This component is central to raising appropriate, custom exceptions for the API wrapper. - -**Related Classes/Methods**: - -* `praw.objector.parse_error:26-48 `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/.codeboarding/Listing_Stream_Processors.json b/.codeboarding/Listing_Stream_Processors.json deleted file mode 100644 index 880cc70bd..000000000 --- a/.codeboarding/Listing_Stream_Processors.json +++ /dev/null @@ -1,136 +0,0 @@ -{ - "description": "This subsystem is responsible for abstracting the complexities of consuming data from the Reddit API, specifically handling paginated \"listings\" (e.g., posts in a subreddit) and continuous \"streams\" of new data (e.g., new comments). It ensures efficient data retrieval, manages pagination state, handles item uniqueness in streams, and implements robust backoff strategies to respect API rate limits.", - "components": [ - { - "name": "ListingGenerator", - "description": "Provides an iterable interface for consuming paginated API responses. It manages the state of pagination, such as the `_after` parameter, to fetch subsequent batches of data seamlessly.", - "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": "ListingBatchFetcher", - "description": "Responsible for fetching a single batch of items from the Reddit API using the underlying `Reddit` client. It utilizes the pagination state provided by `ListingGenerator` to request the correct segment of data.", - "referenced_source_code": [ - { - "qualified_name": "ListingBatchFetcher", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py", - "reference_start_line": 1, - "reference_end_line": 1000 - } - ] - }, - { - "name": "ListingDataExtractor", - "description": "Parses the raw JSON response received from the API, isolating and returning the actual list of data objects (e.g., posts, comments) from the API's wrapper structure.", - "referenced_source_code": [ - { - "qualified_name": "ListingDataExtractor", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py", - "reference_start_line": 1, - "reference_end_line": 1000 - } - ] - }, - { - "name": "ListingParameterMixin", - "description": "Provides common methods for constructing API paths and parameters required for various types of listings. This ensures consistency and reusability across different listing endpoints.", - "referenced_source_code": [ - { - "qualified_name": "ListingParameterMixin", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/mixins/base.py", - "reference_start_line": 1, - "reference_end_line": 1000 - } - ] - }, - { - "name": "StreamProcessor", - "description": "Implements the foundational logic for consuming continuous data streams from the Reddit API. It manages the overall flow, including delays between requests and ensuring resilient fetching.", - "referenced_source_code": [ - { - "qualified_name": "StreamProcessor", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/util.py", - "reference_start_line": 1, - "reference_end_line": 1000 - } - ] - }, - { - "name": "StreamUniquenessManager", - "description": "Maintains a limited set of recently seen items to ensure uniqueness within a data stream. This prevents reprocessing of duplicate items, which is crucial for real-time data consumption.", - "referenced_source_code": [ - { - "qualified_name": "StreamUniquenessManager", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/util.py", - "reference_start_line": 1, - "reference_end_line": 1000 - } - ] - }, - { - "name": "StreamBackoffHandler", - "description": "Implements an exponential backoff strategy to manage delays between stream requests. This is critical for respecting API rate limits and preventing excessive requests that could lead to temporary bans.", - "referenced_source_code": [ - { - "qualified_name": "StreamBackoffHandler", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/util.py", - "reference_start_line": 1, - "reference_end_line": 1000 - } - ] - } - ], - "components_relations": [ - { - "relation": "initiates data retrieval by calling", - "src_name": "ListingGenerator", - "dst_name": "ListingBatchFetcher" - }, - { - "relation": "fetches data and returns it to", - "src_name": "ListingBatchFetcher", - "dst_name": "ListingGenerator" - }, - { - "relation": "invokes", - "src_name": "ListingBatchFetcher", - "dst_name": "ListingDataExtractor" - }, - { - "relation": "provides the extracted list of items back to", - "src_name": "ListingDataExtractor", - "dst_name": "ListingBatchFetcher" - }, - { - "relation": "is utilized by", - "src_name": "ListingParameterMixin", - "dst_name": "ListingBatchFetcher" - }, - { - "relation": "utilizes", - "src_name": "StreamProcessor", - "dst_name": "StreamUniquenessManager" - }, - { - "relation": "provides uniqueness checks for", - "src_name": "StreamUniquenessManager", - "dst_name": "StreamProcessor" - }, - { - "relation": "consults", - "src_name": "StreamProcessor", - "dst_name": "StreamBackoffHandler" - }, - { - "relation": "provides backoff durations to", - "src_name": "StreamBackoffHandler", - "dst_name": "StreamProcessor" - } - ] -} diff --git a/.codeboarding/Listing_Stream_Processors.rst b/.codeboarding/Listing_Stream_Processors.rst deleted file mode 100644 index ec5a2a4fa..000000000 --- a/.codeboarding/Listing_Stream_Processors.rst +++ /dev/null @@ -1,105 +0,0 @@ -Listing Stream Processors -========================= - -.. mermaid:: - - graph LR - ListingGenerator["ListingGenerator"] - ListingBatchFetcher["ListingBatchFetcher"] - ListingDataExtractor["ListingDataExtractor"] - ListingParameterMixin["ListingParameterMixin"] - StreamProcessor["StreamProcessor"] - StreamUniquenessManager["StreamUniquenessManager"] - StreamBackoffHandler["StreamBackoffHandler"] - ListingGenerator -- "initiates data retrieval by calling" --> ListingBatchFetcher - ListingBatchFetcher -- "fetches data and returns it to" --> ListingGenerator - ListingBatchFetcher -- "invokes" --> ListingDataExtractor - ListingDataExtractor -- "provides the extracted list of items back to" --> ListingBatchFetcher - ListingParameterMixin -- "is utilized by" --> ListingBatchFetcher - StreamProcessor -- "utilizes" --> StreamUniquenessManager - StreamUniquenessManager -- "provides uniqueness checks for" --> StreamProcessor - StreamProcessor -- "consults" --> StreamBackoffHandler - StreamBackoffHandler -- "provides backoff durations to" --> StreamProcessor - -| |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 -------- - -This subsystem is responsible for abstracting the complexities of consuming data from the Reddit API, specifically handling paginated "listings" (e.g., posts in a subreddit) and continuous "streams" of new data (e.g., new comments). It ensures efficient data retrieval, manages pagination state, handles item uniqueness in streams, and implements robust backoff strategies to respect API rate limits. - -ListingGenerator -^^^^^^^^^^^^^^^^ - -Provides an iterable interface for consuming paginated API responses. It manages the state of pagination, such as the `_after` parameter, to fetch subsequent batches of data seamlessly. - -**Related Classes/Methods**: - -* `ListingGenerator:17-103 `_ - -ListingBatchFetcher -^^^^^^^^^^^^^^^^^^^ - -Responsible for fetching a single batch of items from the Reddit API using the underlying `Reddit` client. It utilizes the pagination state provided by `ListingGenerator` to request the correct segment of data. - -**Related Classes/Methods**: - -* `ListingBatchFetcher:1-1000 `_ - -ListingDataExtractor -^^^^^^^^^^^^^^^^^^^^ - -Parses the raw JSON response received from the API, isolating and returning the actual list of data objects (e.g., posts, comments) from the API's wrapper structure. - -**Related Classes/Methods**: - -* `ListingDataExtractor:1-1000 `_ - -ListingParameterMixin -^^^^^^^^^^^^^^^^^^^^^ - -Provides common methods for constructing API paths and parameters required for various types of listings. This ensures consistency and reusability across different listing endpoints. - -**Related Classes/Methods**: - -* `ListingParameterMixin:1-1000 `_ - -StreamProcessor -^^^^^^^^^^^^^^^ - -Implements the foundational logic for consuming continuous data streams from the Reddit API. It manages the overall flow, including delays between requests and ensuring resilient fetching. - -**Related Classes/Methods**: - -* `StreamProcessor:1-1000 `_ - -StreamUniquenessManager -^^^^^^^^^^^^^^^^^^^^^^^ - -Maintains a limited set of recently seen items to ensure uniqueness within a data stream. This prevents reprocessing of duplicate items, which is crucial for real-time data consumption. - -**Related Classes/Methods**: - -* `StreamUniquenessManager:1-1000 `_ - -StreamBackoffHandler -^^^^^^^^^^^^^^^^^^^^ - -Implements an exponential backoff strategy to manage delays between stream requests. This is critical for respecting API rate limits and preventing excessive requests that could lead to temporary bans. - -**Related Classes/Methods**: - -* `StreamBackoffHandler:1-1000 `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/.codeboarding/Object_Transformation_Layer.json b/.codeboarding/Object_Transformation_Layer.json deleted file mode 100644 index a7107a99f..000000000 --- a/.codeboarding/Object_Transformation_Layer.json +++ /dev/null @@ -1,87 +0,0 @@ -{ - "description": "The `praw.objector` subsystem is designed to seamlessly convert raw data from the Reddit API into usable PRAW objects while providing robust error handling. The `Objector` class serves as the central entry point, orchestrating the objectification and error-checking processes. The `objectify` method, with the assistance of `_objectify_dict`, recursively transforms complex data structures into their corresponding PRAW object representations. Concurrently, the `check_error` method, by delegating to `parse_error`, ensures that any API-reported errors are properly identified and converted into structured exceptions, maintaining the integrity and reliability of the data processing pipeline. This clear separation of concerns between data transformation and error management allows for a modular and maintainable architecture.", - "components": [ - { - "name": "praw.objector.Objector", - "description": "The central orchestrator of the transformation process, converting raw JSON responses into structured Python objects and managing error detection. It acts as the primary interface for the objectification process.", - "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": "praw.objector.Objector:objectify", - "description": "Implements the core recursive logic for data transformation, traversing raw JSON data, identifying appropriate PRAW object types, and instantiating them. This method is the heart of the data mapping functionality.", - "referenced_source_code": [ - { - "qualified_name": "praw.objector.Objector:objectify", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py", - "reference_start_line": 199, - "reference_end_line": 279 - } - ] - }, - { - "name": "praw.objector.Objector:_objectify_dict", - "description": "A specialized helper method for `objectify`, focusing on converting individual dictionary elements within the raw data into their corresponding PRAW object representations. It handles the granular conversion of data structures.", - "referenced_source_code": [ - { - "qualified_name": "praw.objector.Objector:_objectify_dict", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py", - "reference_start_line": 46, - "reference_end_line": 197 - } - ] - }, - { - "name": "praw.objector.Objector:check_error", - "description": "Responsible for scanning API responses for error indicators and delegating to `parse_error` if an error is detected. This ensures robust error handling within the transformation pipeline.", - "referenced_source_code": [ - { - "qualified_name": "praw.objector.Objector:check_error", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py", - "reference_start_line": 6, - "reference_end_line": 11 - } - ] - }, - { - "name": "praw.objector.Objector:parse_error", - "description": "Interprets raw error data from the API response, converting it into a structured format or raising a specific exception relevant to the PRAW library. This component standardizes error reporting.", - "referenced_source_code": [ - { - "qualified_name": "praw.objector.Objector:parse_error", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py", - "reference_start_line": 13, - "reference_end_line": 44 - } - ] - } - ], - "components_relations": [ - { - "relation": "invokes", - "src_name": "praw.objector.Objector", - "dst_name": "praw.objector.Objector:objectify" - }, - { - "relation": "invokes", - "src_name": "praw.objector.Objector", - "dst_name": "praw.objector.Objector:check_error" - }, - { - "relation": "utilizes", - "src_name": "praw.objector.Objector:objectify", - "dst_name": "praw.objector.Objector:_objectify_dict" - }, - { - "relation": "delegates to", - "src_name": "praw.objector.Objector:check_error", - "dst_name": "praw.objector.Objector:parse_error" - } - ] -} diff --git a/.codeboarding/Object_Transformation_Layer.rst b/.codeboarding/Object_Transformation_Layer.rst deleted file mode 100644 index 2fccb831b..000000000 --- a/.codeboarding/Object_Transformation_Layer.rst +++ /dev/null @@ -1,80 +0,0 @@ -Object Transformation Layer -=========================== - -.. mermaid:: - - graph LR - praw_objector_Objector["praw.objector.Objector"] - praw_objector_Objector_objectify["praw.objector.Objector:objectify"] - praw_objector_Objector__objectify_dict["praw.objector.Objector:_objectify_dict"] - praw_objector_Objector_check_error["praw.objector.Objector:check_error"] - praw_objector_Objector_parse_error["praw.objector.Objector:parse_error"] - praw_objector_Objector -- "invokes" --> praw_objector_Objector_objectify - praw_objector_Objector -- "invokes" --> praw_objector_Objector_check_error - praw_objector_Objector_objectify -- "utilizes" --> praw_objector_Objector__objectify_dict - praw_objector_Objector_check_error -- "delegates to" --> praw_objector_Objector_parse_error - -| |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.objector` subsystem is designed to seamlessly convert raw data from the Reddit API into usable PRAW objects while providing robust error handling. The `Objector` class serves as the central entry point, orchestrating the objectification and error-checking processes. The `objectify` method, with the assistance of `_objectify_dict`, recursively transforms complex data structures into their corresponding PRAW object representations. Concurrently, the `check_error` method, by delegating to `parse_error`, ensures that any API-reported errors are properly identified and converted into structured exceptions, maintaining the integrity and reliability of the data processing pipeline. This clear separation of concerns between data transformation and error management allows for a modular and maintainable architecture. - -praw.objector.Objector -^^^^^^^^^^^^^^^^^^^^^^ - -The central orchestrator of the transformation process, converting raw JSON responses into structured Python objects and managing error detection. It acts as the primary interface for the objectification process. - -**Related Classes/Methods**: - -* `praw.objector.Objector:17-263 `_ - -praw.objector.Objector:objectify -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Implements the core recursive logic for data transformation, traversing raw JSON data, identifying appropriate PRAW object types, and instantiating them. This method is the heart of the data mapping functionality. - -**Related Classes/Methods**: - -* `praw.objector.Objector:objectify:199-279 `_ - -praw.objector.Objector:_objectify_dict -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -A specialized helper method for `objectify`, focusing on converting individual dictionary elements within the raw data into their corresponding PRAW object representations. It handles the granular conversion of data structures. - -**Related Classes/Methods**: - -* `praw.objector.Objector:_objectify_dict:46-197 `_ - -praw.objector.Objector:check_error -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Responsible for scanning API responses for error indicators and delegating to `parse_error` if an error is detected. This ensures robust error handling within the transformation pipeline. - -**Related Classes/Methods**: - -* `praw.objector.Objector:check_error:6-11 `_ - -praw.objector.Objector:parse_error -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Interprets raw error data from the API response, converting it into a structured format or raising a specific exception relevant to the PRAW library. This component standardizes error reporting. - -**Related Classes/Methods**: - -* `praw.objector.Objector:parse_error:13-44 `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/.codeboarding/Reddit_Data_Models.json b/.codeboarding/Reddit_Data_Models.json deleted file mode 100644 index 9b32e3ace..000000000 --- a/.codeboarding/Reddit_Data_Models.json +++ /dev/null @@ -1,138 +0,0 @@ -{ - "description": "The PRAW library's core architecture for interacting with Reddit content is centered around key models representing Reddit entities. The Subreddit component acts as a central hub for community-specific interactions, enabling the creation and retrieval of Submission objects. Submission objects, in turn, manage post data and facilitate interactions with Comment threads. Both Submission and Comment leverage the VotableMixin for consistent voting functionality, demonstrating effective code reuse through inheritance. User-centric operations are handled by the Redditor component, which is involved in Modmail conversations. Modmail itself is composed by Subreddit, indicating its role in community moderation. LiveThread and WikiPage represent distinct content streams and informational pages, with WikiPage being directly associated with a Subreddit. This design emphasizes a clear separation of concerns, with each component encapsulating specific Reddit functionality and interacting through well-defined relationships to manage and present Reddit data.", - "components": [ - { - "name": "Subreddit", - "description": "Manages subreddit data, submissions, moderation, flair, and style. It acts as a primary facade for subreddit-specific API calls, allowing users to interact with a community's content and settings.", - "referenced_source_code": [ - { - "qualified_name": "praw.models.reddit.subreddit.Subreddit", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/subreddit.py", - "reference_start_line": 2446, - "reference_end_line": 2446 - } - ] - }, - { - "name": "Submission", - "description": "Encapsulates Reddit post data, including content, flair, and moderation status. It provides methods for retrieving content and interacting with the post (e.g., voting, commenting).", - "referenced_source_code": [ - { - "qualified_name": "praw.models.reddit.submission.Submission", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/submission.py", - "reference_start_line": 716, - "reference_end_line": 716 - } - ] - }, - { - "name": "Comment", - "description": "Manages individual comment data, including its content, author, and hierarchical position within a discussion. It provides methods for moderation and navigating comment threads.", - "referenced_source_code": [ - { - "qualified_name": "Comment", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", - "reference_start_line": 582, - "reference_end_line": 596 - } - ] - }, - { - "name": "Redditor", - "description": "Provides access to user-specific information, including profile details, submitted content, and comments. It enables interactions related to a specific Reddit user.", - "referenced_source_code": [ - { - "qualified_name": "Redditor", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", - "reference_start_line": 810, - "reference_end_line": 819 - } - ] - }, - { - "name": "VotableMixin", - "description": "A mixin class that provides common voting functionality (upvote, downvote, clear vote) to any Reddit entity that can be voted on. This promotes code reuse and consistency across votable models.", - "referenced_source_code": [ - { - "qualified_name": "VotableMixin", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/votable.py", - "reference_start_line": 8, - "reference_end_line": 92 - } - ] - }, - { - "name": "Modmail", - "description": "Represents a modmail conversation, facilitating communication between moderators and users, or between moderators themselves. It encapsulates messages and conversation states.", - "referenced_source_code": [ - { - "qualified_name": "Modmail", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/subreddit.py", - "reference_start_line": 2627, - "reference_end_line": 2639 - } - ] - }, - { - "name": "LiveThread", - "description": "Manages data and interactions for Reddit Live Threads, which are real-time, event-driven content streams. It provides access to updates and thread metadata.", - "referenced_source_code": [ - { - "qualified_name": "LiveThread", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/live.py", - "reference_start_line": 261, - "reference_end_line": 471 - } - ] - }, - { - "name": "WikiPage", - "description": "Abstracts the content and moderation aspects of a Reddit Wiki Page. It allows for retrieval, editing, and management of wiki content within a subreddit.", - "referenced_source_code": [ - { - "qualified_name": "WikiPage", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/wikipage.py", - "reference_start_line": 146, - "reference_end_line": 314 - } - ] - } - ], - "components_relations": [ - { - "relation": "creates and fetches", - "src_name": "Subreddit", - "dst_name": "Submission" - }, - { - "relation": "composes", - "src_name": "Subreddit", - "dst_name": "Modmail" - }, - { - "relation": "retrieves and references", - "src_name": "Submission", - "dst_name": "Comment" - }, - { - "relation": "inherits from", - "src_name": "Submission", - "dst_name": "VotableMixin" - }, - { - "relation": "inherits from", - "src_name": "Comment", - "dst_name": "VotableMixin" - }, - { - "relation": "involves", - "src_name": "Modmail", - "dst_name": "Redditor" - }, - { - "relation": "associated with", - "src_name": "WikiPage", - "dst_name": "Subreddit" - } - ] -} diff --git a/.codeboarding/Reddit_Data_Models.rst b/.codeboarding/Reddit_Data_Models.rst deleted file mode 100644 index d6e6f9d3a..000000000 --- a/.codeboarding/Reddit_Data_Models.rst +++ /dev/null @@ -1,113 +0,0 @@ -Reddit Data Models -================== - -.. mermaid:: - - graph LR - Subreddit["Subreddit"] - Submission["Submission"] - Comment["Comment"] - Redditor["Redditor"] - VotableMixin["VotableMixin"] - Modmail["Modmail"] - LiveThread["LiveThread"] - WikiPage["WikiPage"] - Subreddit -- "creates and fetches" --> Submission - Subreddit -- "composes" --> Modmail - Submission -- "retrieves and references" --> Comment - Submission -- "inherits from" --> VotableMixin - Comment -- "inherits from" --> VotableMixin - Modmail -- "involves" --> Redditor - WikiPage -- "associated with" --> Subreddit - -| |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 for interacting with Reddit content is centered around key models representing Reddit entities. The Subreddit component acts as a central hub for community-specific interactions, enabling the creation and retrieval of Submission objects. Submission objects, in turn, manage post data and facilitate interactions with Comment threads. Both Submission and Comment leverage the VotableMixin for consistent voting functionality, demonstrating effective code reuse through inheritance. User-centric operations are handled by the Redditor component, which is involved in Modmail conversations. Modmail itself is composed by Subreddit, indicating its role in community moderation. LiveThread and WikiPage represent distinct content streams and informational pages, with WikiPage being directly associated with a Subreddit. This design emphasizes a clear separation of concerns, with each component encapsulating specific Reddit functionality and interacting through well-defined relationships to manage and present Reddit data. - -Subreddit -^^^^^^^^^ - -Manages subreddit data, submissions, moderation, flair, and style. It acts as a primary facade for subreddit-specific API calls, allowing users to interact with a community's content and settings. - -**Related Classes/Methods**: - -* `praw.models.reddit.subreddit.Subreddit `_ - -Submission -^^^^^^^^^^ - -Encapsulates Reddit post data, including content, flair, and moderation status. It provides methods for retrieving content and interacting with the post (e.g., voting, commenting). - -**Related Classes/Methods**: - -* `praw.models.reddit.submission.Submission `_ - -Comment -^^^^^^^ - -Manages individual comment data, including its content, author, and hierarchical position within a discussion. It provides methods for moderation and navigating comment threads. - -**Related Classes/Methods**: - -* `Comment:582-596 `_ - -Redditor -^^^^^^^^ - -Provides access to user-specific information, including profile details, submitted content, and comments. It enables interactions related to a specific Reddit user. - -**Related Classes/Methods**: - -* `Redditor:810-819 `_ - -VotableMixin -^^^^^^^^^^^^ - -A mixin class that provides common voting functionality (upvote, downvote, clear vote) to any Reddit entity that can be voted on. This promotes code reuse and consistency across votable models. - -**Related Classes/Methods**: - -* `VotableMixin:8-92 `_ - -Modmail -^^^^^^^ - -Represents a modmail conversation, facilitating communication between moderators and users, or between moderators themselves. It encapsulates messages and conversation states. - -**Related Classes/Methods**: - -* `Modmail:2627-2639 `_ - -LiveThread -^^^^^^^^^^ - -Manages data and interactions for Reddit Live Threads, which are real-time, event-driven content streams. It provides access to updates and thread metadata. - -**Related Classes/Methods**: - -* `LiveThread:261-471 `_ - -WikiPage -^^^^^^^^ - -Abstracts the content and moderation aspects of a Reddit Wiki Page. It allows for retrieval, editing, and management of wiki content within a subreddit. - -**Related Classes/Methods**: - -* `WikiPage:146-314 `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/.codeboarding/analysis.json b/.codeboarding/analysis.json deleted file mode 100644 index c12ed25c3..000000000 --- a/.codeboarding/analysis.json +++ /dev/null @@ -1,211 +0,0 @@ -{ - "description": "The PRAW architecture is designed as a robust API wrapper, providing an object-oriented interface to the Reddit API. It centers around the `API Client Core`, which orchestrates all network interactions, leveraging the `Configuration Manager` for settings and delegating raw response processing to the `Object Transformation Layer`. This layer is responsible for mapping raw API data into rich `Reddit Data Models`, which encapsulate Reddit entities and their behaviors. For handling collections and real-time data, the `Listing & Stream Processors` work in conjunction with the `API Client Core` and `Reddit Data Models`. Critical to its reliability, the `Exception Handling` component provides structured error reporting across the system. This design ensures a clear separation of concerns, facilitating maintainability, extensibility, and a developer-friendly experience, making it ideal for both documentation and visual flow graph representation.", - "components": [ - { - "name": "API Client Core", - "description": "The central orchestrator for all interactions with the Reddit API, managing HTTP requests, authentication, and rate limiting.", - "referenced_source_code": [ - { - "qualified_name": "praw.reddit.Reddit.__init__", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", - "reference_start_line": 1, - "reference_end_line": 1 - }, - { - "qualified_name": "praw.reddit.Reddit.request", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", - "reference_start_line": 1, - "reference_end_line": 1 - }, - { - "qualified_name": "praw.reddit.Reddit._objectify_request", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", - "reference_start_line": 1, - "reference_end_line": 1 - }, - { - "qualified_name": "praw.reddit.Reddit._handle_rate_limit", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", - "reference_start_line": 1, - "reference_end_line": 1 - } - ], - "can_expand": true - }, - { - "name": "Configuration Manager", - "description": "Handles the loading, storage, and provision of PRAW's operational settings, including API credentials and user agent strings.", - "referenced_source_code": [ - { - "qualified_name": "praw.config.Config.__init__", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/config.py", - "reference_start_line": 1, - "reference_end_line": 1 - }, - { - "qualified_name": "praw.config.Config._load_config", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/config.py", - "reference_start_line": 1, - "reference_end_line": 1 - } - ], - "can_expand": false - }, - { - "name": "Object Transformation Layer", - "description": "Acts as a data mapper, converting raw JSON responses from the Reddit API into rich, object-oriented Python representations (`Reddit Data Models`).", - "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 - }, - { - "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 - } - ], - "can_expand": true - }, - { - "name": "Reddit Data Models", - "description": "A comprehensive set of classes representing various Reddit entities (e.g., `Subreddit`, `Submission`, `Comment`, `Redditor`). These models encapsulate data and provide high-level methods for interacting with their respective API endpoints.", - "referenced_source_code": [ - { - "qualified_name": "praw.models.reddit.subreddit.Subreddit.submit", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/subreddit.py", - "reference_start_line": 1, - "reference_end_line": 1 - }, - { - "qualified_name": "praw.models.reddit.submission.Submission._fetch_data", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/submission.py", - "reference_start_line": 1, - "reference_end_line": 1 - }, - { - "qualified_name": "praw.models.reddit.comment.Comment.parent", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/comment.py", - "reference_start_line": 1, - "reference_end_line": 1 - }, - { - "qualified_name": "praw.models.reddit.redditor.Redditor._fetch_info", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/redditor.py", - "reference_start_line": 1, - "reference_end_line": 1 - }, - { - "qualified_name": "praw.models.reddit.mixins.votable.VotableMixin._vote", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/votable.py", - "reference_start_line": 1, - "reference_end_line": 1 - } - ], - "can_expand": true - }, - { - "name": "Listing & Stream Processors", - "description": "Provides mechanisms for iterating through paginated API responses (listings) and consuming real-time data streams from Reddit, handling pagination logic and item uniqueness.", - "referenced_source_code": [ - { - "qualified_name": "praw.models.listing.generator.ListingGenerator.__next__", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py", - "reference_start_line": 1, - "reference_end_line": 1 - }, - { - "qualified_name": "praw.models.listing.generator.ListingGenerator._next_batch", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py", - "reference_start_line": 1, - "reference_end_line": 1 - } - ], - "can_expand": true - }, - { - "name": "Exception Handling", - "description": "Defines a hierarchy of custom exception classes specific to PRAW and provides utilities to translate raw API error messages into structured exceptions.", - "referenced_source_code": [ - { - "qualified_name": "praw.exceptions.PRAWException", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py", - "reference_start_line": 14, - "reference_end_line": 15 - }, - { - "qualified_name": "praw.exceptions.parse_exception_list", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py", - "reference_start_line": 173, - "reference_end_line": 189 - } - ], - "can_expand": false - } - ], - "components_relations": [ - { - "relation": "uses", - "src_name": "API Client Core", - "dst_name": "Configuration Manager" - }, - { - "relation": "sends raw responses to", - "src_name": "API Client Core", - "dst_name": "Object Transformation Layer" - }, - { - "relation": "reports errors to", - "src_name": "API Client Core", - "dst_name": "Exception Handling" - }, - { - "relation": "receives raw responses from", - "src_name": "Object Transformation Layer", - "dst_name": "API Client Core" - }, - { - "relation": "instantiates", - "src_name": "Object Transformation Layer", - "dst_name": "Reddit Data Models" - }, - { - "relation": "parses errors with", - "src_name": "Object Transformation Layer", - "dst_name": "Exception Handling" - }, - { - "relation": "initiates requests via", - "src_name": "Reddit Data Models", - "dst_name": "API Client Core" - }, - { - "relation": "are utilized by", - "src_name": "Reddit Data Models", - "dst_name": "Listing & Stream Processors" - }, - { - "relation": "fetches batches via", - "src_name": "Listing & Stream Processors", - "dst_name": "API Client Core" - }, - { - "relation": "utilizes", - "src_name": "Listing & Stream Processors", - "dst_name": "Reddit Data Models" - }, - { - "relation": "receives errors from", - "src_name": "Exception Handling", - "dst_name": "API Client Core" - }, - { - "relation": "receives parsed errors from", - "src_name": "Exception Handling", - "dst_name": "Object Transformation Layer" - } - ] -} diff --git a/.codeboarding/codeboarding_version.json b/.codeboarding/codeboarding_version.json deleted file mode 100644 index 5bb933317..000000000 --- a/.codeboarding/codeboarding_version.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "commit_hash": "ca26447b46c4c563b2d18cd0a82f1b18f576dc34", - "code_boarding_version": "0.1.0" -} diff --git a/.codeboarding/overview.rst b/.codeboarding/overview.rst deleted file mode 100644 index 66ccf0d12..000000000 --- a/.codeboarding/overview.rst +++ /dev/null @@ -1,124 +0,0 @@ -Overview -======== - -.. mermaid:: - - graph LR - API_Client_Core["API Client Core"] - Configuration_Manager["Configuration Manager"] - Object_Transformation_Layer["Object Transformation Layer"] - Reddit_Data_Models["Reddit Data Models"] - Listing_Stream_Processors["Listing & Stream Processors"] - Exception_Handling["Exception Handling"] - API_Client_Core -- "uses" --> Configuration_Manager - API_Client_Core -- "sends raw responses to" --> Object_Transformation_Layer - API_Client_Core -- "reports errors to" --> Exception_Handling - Object_Transformation_Layer -- "receives raw responses from" --> API_Client_Core - Object_Transformation_Layer -- "instantiates" --> Reddit_Data_Models - Object_Transformation_Layer -- "parses errors with" --> Exception_Handling - Reddit_Data_Models -- "initiates requests via" --> API_Client_Core - Reddit_Data_Models -- "are utilized by" --> Listing_Stream_Processors - Listing_Stream_Processors -- "fetches batches via" --> API_Client_Core - Listing_Stream_Processors -- "utilizes" --> Reddit_Data_Models - Exception_Handling -- "receives errors from" --> API_Client_Core - Exception_Handling -- "receives parsed errors from" --> Object_Transformation_Layer - click API_Client_Core href "https://github.com/praw-dev/praw/blob/main/.codeboarding/API_Client_Core.html" "Details" - click Object_Transformation_Layer href "https://github.com/praw-dev/praw/blob/main/.codeboarding/Object_Transformation_Layer.html" "Details" - click Reddit_Data_Models href "https://github.com/praw-dev/praw/blob/main/.codeboarding/Reddit_Data_Models.html" "Details" - click Listing_Stream_Processors href "https://github.com/praw-dev/praw/blob/main/.codeboarding/Listing_Stream_Processors.html" "Details" - click Exception_Handling href "https://github.com/praw-dev/praw/blob/main/.codeboarding/Exception_Handling.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 architecture is designed as a robust API wrapper, providing an object-oriented interface to the Reddit API. It centers around the `API Client Core`, which orchestrates all network interactions, leveraging the `Configuration Manager` for settings and delegating raw response processing to the `Object Transformation Layer`. This layer is responsible for mapping raw API data into rich `Reddit Data Models`, which encapsulate Reddit entities and their behaviors. For handling collections and real-time data, the `Listing & Stream Processors` work in conjunction with the `API Client Core` and `Reddit Data Models`. Critical to its reliability, the `Exception Handling` component provides structured error reporting across the system. This design ensures a clear separation of concerns, facilitating maintainability, extensibility, and a developer-friendly experience, making it ideal for both documentation and visual flow graph representation. - -API Client Core -^^^^^^^^^^^^^^^ - -:ref:`Expand ` - -The central orchestrator for all interactions with the Reddit API, managing HTTP requests, authentication, and rate limiting. - -**Related Classes/Methods**: - -* `praw.reddit.Reddit.__init__ `_ -* `praw.reddit.Reddit.request `_ -* `praw.reddit.Reddit._objectify_request `_ -* `praw.reddit.Reddit._handle_rate_limit `_ - -Configuration Manager -^^^^^^^^^^^^^^^^^^^^^ - -Handles the loading, storage, and provision of PRAW's operational settings, including API credentials and user agent strings. - -**Related Classes/Methods**: - -* `praw.config.Config.__init__ `_ -* `praw.config.Config._load_config `_ - -Object Transformation Layer -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:ref:`Expand ` - -Acts as a data mapper, converting raw JSON responses from the Reddit API into rich, object-oriented Python representations (`Reddit Data Models`). - -**Related Classes/Methods**: - -* `praw.objector.Objector.objectify `_ -* `praw.objector.Objector.check_error `_ - -Reddit Data Models -^^^^^^^^^^^^^^^^^^ - -:ref:`Expand ` - -A comprehensive set of classes representing various Reddit entities (e.g., `Subreddit`, `Submission`, `Comment`, `Redditor`). These models encapsulate data and provide high-level methods for interacting with their respective API endpoints. - -**Related Classes/Methods**: - -* `praw.models.reddit.subreddit.Subreddit.submit `_ -* `praw.models.reddit.submission.Submission._fetch_data `_ -* `praw.models.reddit.comment.Comment.parent `_ -* `praw.models.reddit.redditor.Redditor._fetch_info `_ -* `praw.models.reddit.mixins.votable.VotableMixin._vote `_ - -Listing & Stream Processors -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:ref:`Expand ` - -Provides mechanisms for iterating through paginated API responses (listings) and consuming real-time data streams from Reddit, handling pagination logic and item uniqueness. - -**Related Classes/Methods**: - -* `praw.models.listing.generator.ListingGenerator.__next__ `_ -* `praw.models.listing.generator.ListingGenerator._next_batch `_ - -Exception Handling -^^^^^^^^^^^^^^^^^^ - -:ref:`Expand ` - -Defines a hierarchy of custom exception classes specific to PRAW and provides utilities to translate raw API error messages into structured exceptions. - -**Related Classes/Methods**: - -* `praw.exceptions.PRAWException:14-15 `_ -* `praw.exceptions.parse_exception_list:173-189 `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/docs/architecture_overview/API_Client_Core.rst b/docs/architecture_overview/API_Client_Core.rst deleted file mode 100644 index a71c8d5b6..000000000 --- a/docs/architecture_overview/API_Client_Core.rst +++ /dev/null @@ -1,115 +0,0 @@ -Api Client Core -=============== - -.. mermaid:: - - graph LR - API_Client_Core["API Client Core"] - Client_Initializer["Client Initializer"] - Request_Executor["Request Executor"] - Response_Objectifier["Response Objectifier"] - Rate_Limit_Manager["Rate Limit Manager"] - API_Operation_Methods["API Operation Methods"] - Async_Checker["Async Checker"] - Client_Initializer -- "initializes" --> API_Client_Core - API_Client_Core -- "manages" --> Request_Executor - API_Client_Core -- "manages" --> Response_Objectifier - API_Client_Core -- "manages" --> Rate_Limit_Manager - API_Client_Core -- "exposes" --> API_Operation_Methods - API_Operation_Methods -- "invokes" --> Request_Executor - Request_Executor -- "checks" --> Async_Checker - Request_Executor -- "returns raw response to" --> Response_Objectifier - Response_Objectifier -- "transforms for" --> API_Operation_Methods - API_Operation_Methods -- "consults" --> Rate_Limit_Manager - click API_Client_Core href "https://github.com/praw-dev/praw/blob/main/.codeboarding/API_Client_Core.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 Reddit API client is structured around the `API Client Core`, which serves as the primary interface for users. This core is set up by the `Client Initializer`, configuring essential components like the HTTP client and response parsing. User interactions, such as fetching data or creating posts, are handled by `API Operation Methods`. These methods delegate the actual HTTP communication to the `Request Executor`, which may consult the `Async Checker` for proper asynchronous execution. Upon receiving a raw response, the `Request Executor` passes it to the `Response Objectifier` for transformation into structured Python objects, which are then returned to the `API Operation Methods`. Throughout this process, the `Rate Limit Manager` is consulted to ensure adherence to Reddit's API usage policies, with the `API Client Core` overseeing and managing these interactions. - -API Client Core -^^^^^^^^^^^^^^^ - -:ref:`Expand ` - -Serves as the main entry point for users to interact with the Reddit API. It orchestrates all underlying operations, manages the client's state, and exposes a high-level, object-oriented interface. - -**Related Classes/Methods**: - -* `praw.reddit.Reddit:57-901 `_ - -Client Initializer -^^^^^^^^^^^^^^^^^^ - -Sets up the API Client Core instance, including configuring the underlying HTTP client (prawcore) and the response objectification mechanism. It integrates `prawcore` for HTTP requests and the `Objector` for response parsing. - -**Related Classes/Methods**: - -* `praw.reddit.Reddit.__init__ `_ -* `praw.reddit._prepare_prawcore:527-546 `_ -* `praw.reddit._prepare_objector:479-525 `_ - -Request Executor -^^^^^^^^^^^^^^^^ - -Executes the raw HTTP requests to the Reddit API, handling the low-level communication details. - -**Related Classes/Methods**: - -* `praw.reddit.Reddit.request `_ - -Response Objectifier -^^^^^^^^^^^^^^^^^^^^ - -Transforms the raw JSON responses from the API into structured PRAW Python objects, making them easier to consume and work with. - -**Related Classes/Methods**: - -* `praw.reddit.Reddit._objectify_request `_ - -Rate Limit Manager -^^^^^^^^^^^^^^^^^^ - -Monitors and enforces Reddit's API rate limits, pausing requests when necessary to prevent exceeding usage quotas and ensuring compliance. - -**Related Classes/Methods**: - -* `praw.reddit.Reddit._handle_rate_limit `_ - -API Operation Methods -^^^^^^^^^^^^^^^^^^^^^ - -Provide specific, high-level methods for common API operations (e.g., fetching data, creating posts, deleting resources), abstracting the underlying request and response handling details from the end-user. - -**Related Classes/Methods**: - -* `praw.reddit.Reddit.get `_ -* `praw.reddit.Reddit.post `_ -* `praw.reddit.Reddit.delete `_ -* `praw.reddit.Reddit.patch `_ -* `praw.reddit.Reddit.put `_ - -Async Checker -^^^^^^^^^^^^^ - -Manages and verifies the asynchronous context for operations, ensuring proper execution in async environments. - -**Related Classes/Methods**: - -* `praw.reddit._check_for_async:388-411 `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/docs/architecture_overview/Exception_Handling.rst b/docs/architecture_overview/Exception_Handling.rst deleted file mode 100644 index 847c6a78e..000000000 --- a/docs/architecture_overview/Exception_Handling.rst +++ /dev/null @@ -1,80 +0,0 @@ -Exception Handling -================== - -.. mermaid:: - - graph LR - ExceptionBase["ExceptionBase"] - ErrorItem["ErrorItem"] - ErrorParser["ErrorParser"] - ErrorDetector["ErrorDetector"] - ExceptionFactory["ExceptionFactory"] - ErrorDetector -- "delegates error parsing to" --> ExceptionFactory - ExceptionFactory -- "converts raw errors to structured items via" --> ErrorParser - ErrorParser -- "creates" --> ErrorItem - ExceptionFactory -- "raises" --> ExceptionBase - -| |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 error handling subsystem efficiently processes raw API responses into structured, actionable exceptions. The `ErrorDetector` initiates the process by identifying potential errors in API responses, subsequently delegating their detailed parsing to the `ExceptionFactory`. The `ExceptionFactory` then leverages the `ErrorParser` to transform raw error data into standardized `ErrorItem` objects. Finally, based on these structured error details, the `ExceptionFactory` constructs and raises appropriate custom exceptions, all derived from the foundational `ExceptionBase`, providing a consistent and predictable error interface for developers. - -ExceptionBase -^^^^^^^^^^^^^ - -The foundational base class for all custom exceptions within PRAW. It establishes a consistent error handling mechanism across the library and provides a unified structure for reporting and handling errors. This is critical for an API wrapper to provide a predictable error interface to developers. - -**Related Classes/Methods**: - -* `praw.exceptions.PRAWException:14-15 `_ - -ErrorItem -^^^^^^^^^ - -A data structure that encapsulates the details of a single, specific error returned by the Reddit API. It provides a standardized and easily accessible format for error information, transforming raw API responses into structured, consumable objects. This component is vital for abstracting raw API error messages into a developer-friendly format. - -**Related Classes/Methods**: - -* `praw.exceptions.RedditErrorItem:18-71 `_ - -ErrorParser -^^^^^^^^^^^ - -A crucial utility function responsible for transforming raw, unstructured error data received from the Reddit API into a list of structured `ErrorItem` objects. It acts as a parser, converting raw error dictionaries into `praw.exceptions.RedditErrorItem` instances, which is essential for making API errors manageable. - -**Related Classes/Methods**: - -* `praw.exceptions.parse_exception_list:173-189 `_ - -ErrorDetector -^^^^^^^^^^^^^ - -The initial entry point for error detection within API responses. It acts as a preliminary gatekeeper that identifies potential errors in the raw API response and delegates further processing. This component is the first line of defense in the error handling pipeline, ensuring that only responses with potential errors are further processed. - -**Related Classes/Methods**: - -* `praw.objector.check_error:20-24 `_ - -ExceptionFactory -^^^^^^^^^^^^^^^^ - -The core orchestrator for converting raw API error structures into PRAW-specific exception objects. It manages the flow from raw error data to structured exceptions, acting as an adapter between the raw API error format and PRAW's internal exception system. This component is central to raising appropriate, custom exceptions for the API wrapper. - -**Related Classes/Methods**: - -* `praw.objector.parse_error:26-48 `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/docs/architecture_overview/Listing_Stream_Processors.rst b/docs/architecture_overview/Listing_Stream_Processors.rst deleted file mode 100644 index ec5a2a4fa..000000000 --- a/docs/architecture_overview/Listing_Stream_Processors.rst +++ /dev/null @@ -1,105 +0,0 @@ -Listing Stream Processors -========================= - -.. mermaid:: - - graph LR - ListingGenerator["ListingGenerator"] - ListingBatchFetcher["ListingBatchFetcher"] - ListingDataExtractor["ListingDataExtractor"] - ListingParameterMixin["ListingParameterMixin"] - StreamProcessor["StreamProcessor"] - StreamUniquenessManager["StreamUniquenessManager"] - StreamBackoffHandler["StreamBackoffHandler"] - ListingGenerator -- "initiates data retrieval by calling" --> ListingBatchFetcher - ListingBatchFetcher -- "fetches data and returns it to" --> ListingGenerator - ListingBatchFetcher -- "invokes" --> ListingDataExtractor - ListingDataExtractor -- "provides the extracted list of items back to" --> ListingBatchFetcher - ListingParameterMixin -- "is utilized by" --> ListingBatchFetcher - StreamProcessor -- "utilizes" --> StreamUniquenessManager - StreamUniquenessManager -- "provides uniqueness checks for" --> StreamProcessor - StreamProcessor -- "consults" --> StreamBackoffHandler - StreamBackoffHandler -- "provides backoff durations to" --> StreamProcessor - -| |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 -------- - -This subsystem is responsible for abstracting the complexities of consuming data from the Reddit API, specifically handling paginated "listings" (e.g., posts in a subreddit) and continuous "streams" of new data (e.g., new comments). It ensures efficient data retrieval, manages pagination state, handles item uniqueness in streams, and implements robust backoff strategies to respect API rate limits. - -ListingGenerator -^^^^^^^^^^^^^^^^ - -Provides an iterable interface for consuming paginated API responses. It manages the state of pagination, such as the `_after` parameter, to fetch subsequent batches of data seamlessly. - -**Related Classes/Methods**: - -* `ListingGenerator:17-103 `_ - -ListingBatchFetcher -^^^^^^^^^^^^^^^^^^^ - -Responsible for fetching a single batch of items from the Reddit API using the underlying `Reddit` client. It utilizes the pagination state provided by `ListingGenerator` to request the correct segment of data. - -**Related Classes/Methods**: - -* `ListingBatchFetcher:1-1000 `_ - -ListingDataExtractor -^^^^^^^^^^^^^^^^^^^^ - -Parses the raw JSON response received from the API, isolating and returning the actual list of data objects (e.g., posts, comments) from the API's wrapper structure. - -**Related Classes/Methods**: - -* `ListingDataExtractor:1-1000 `_ - -ListingParameterMixin -^^^^^^^^^^^^^^^^^^^^^ - -Provides common methods for constructing API paths and parameters required for various types of listings. This ensures consistency and reusability across different listing endpoints. - -**Related Classes/Methods**: - -* `ListingParameterMixin:1-1000 `_ - -StreamProcessor -^^^^^^^^^^^^^^^ - -Implements the foundational logic for consuming continuous data streams from the Reddit API. It manages the overall flow, including delays between requests and ensuring resilient fetching. - -**Related Classes/Methods**: - -* `StreamProcessor:1-1000 `_ - -StreamUniquenessManager -^^^^^^^^^^^^^^^^^^^^^^^ - -Maintains a limited set of recently seen items to ensure uniqueness within a data stream. This prevents reprocessing of duplicate items, which is crucial for real-time data consumption. - -**Related Classes/Methods**: - -* `StreamUniquenessManager:1-1000 `_ - -StreamBackoffHandler -^^^^^^^^^^^^^^^^^^^^ - -Implements an exponential backoff strategy to manage delays between stream requests. This is critical for respecting API rate limits and preventing excessive requests that could lead to temporary bans. - -**Related Classes/Methods**: - -* `StreamBackoffHandler:1-1000 `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/docs/architecture_overview/Object_Transformation_Layer.rst b/docs/architecture_overview/Object_Transformation_Layer.rst deleted file mode 100644 index 2fccb831b..000000000 --- a/docs/architecture_overview/Object_Transformation_Layer.rst +++ /dev/null @@ -1,80 +0,0 @@ -Object Transformation Layer -=========================== - -.. mermaid:: - - graph LR - praw_objector_Objector["praw.objector.Objector"] - praw_objector_Objector_objectify["praw.objector.Objector:objectify"] - praw_objector_Objector__objectify_dict["praw.objector.Objector:_objectify_dict"] - praw_objector_Objector_check_error["praw.objector.Objector:check_error"] - praw_objector_Objector_parse_error["praw.objector.Objector:parse_error"] - praw_objector_Objector -- "invokes" --> praw_objector_Objector_objectify - praw_objector_Objector -- "invokes" --> praw_objector_Objector_check_error - praw_objector_Objector_objectify -- "utilizes" --> praw_objector_Objector__objectify_dict - praw_objector_Objector_check_error -- "delegates to" --> praw_objector_Objector_parse_error - -| |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.objector` subsystem is designed to seamlessly convert raw data from the Reddit API into usable PRAW objects while providing robust error handling. The `Objector` class serves as the central entry point, orchestrating the objectification and error-checking processes. The `objectify` method, with the assistance of `_objectify_dict`, recursively transforms complex data structures into their corresponding PRAW object representations. Concurrently, the `check_error` method, by delegating to `parse_error`, ensures that any API-reported errors are properly identified and converted into structured exceptions, maintaining the integrity and reliability of the data processing pipeline. This clear separation of concerns between data transformation and error management allows for a modular and maintainable architecture. - -praw.objector.Objector -^^^^^^^^^^^^^^^^^^^^^^ - -The central orchestrator of the transformation process, converting raw JSON responses into structured Python objects and managing error detection. It acts as the primary interface for the objectification process. - -**Related Classes/Methods**: - -* `praw.objector.Objector:17-263 `_ - -praw.objector.Objector:objectify -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Implements the core recursive logic for data transformation, traversing raw JSON data, identifying appropriate PRAW object types, and instantiating them. This method is the heart of the data mapping functionality. - -**Related Classes/Methods**: - -* `praw.objector.Objector:objectify:199-279 `_ - -praw.objector.Objector:_objectify_dict -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -A specialized helper method for `objectify`, focusing on converting individual dictionary elements within the raw data into their corresponding PRAW object representations. It handles the granular conversion of data structures. - -**Related Classes/Methods**: - -* `praw.objector.Objector:_objectify_dict:46-197 `_ - -praw.objector.Objector:check_error -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Responsible for scanning API responses for error indicators and delegating to `parse_error` if an error is detected. This ensures robust error handling within the transformation pipeline. - -**Related Classes/Methods**: - -* `praw.objector.Objector:check_error:6-11 `_ - -praw.objector.Objector:parse_error -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Interprets raw error data from the API response, converting it into a structured format or raising a specific exception relevant to the PRAW library. This component standardizes error reporting. - -**Related Classes/Methods**: - -* `praw.objector.Objector:parse_error:13-44 `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/docs/architecture_overview/Reddit_Data_Models.rst b/docs/architecture_overview/Reddit_Data_Models.rst deleted file mode 100644 index d6e6f9d3a..000000000 --- a/docs/architecture_overview/Reddit_Data_Models.rst +++ /dev/null @@ -1,113 +0,0 @@ -Reddit Data Models -================== - -.. mermaid:: - - graph LR - Subreddit["Subreddit"] - Submission["Submission"] - Comment["Comment"] - Redditor["Redditor"] - VotableMixin["VotableMixin"] - Modmail["Modmail"] - LiveThread["LiveThread"] - WikiPage["WikiPage"] - Subreddit -- "creates and fetches" --> Submission - Subreddit -- "composes" --> Modmail - Submission -- "retrieves and references" --> Comment - Submission -- "inherits from" --> VotableMixin - Comment -- "inherits from" --> VotableMixin - Modmail -- "involves" --> Redditor - WikiPage -- "associated with" --> Subreddit - -| |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 for interacting with Reddit content is centered around key models representing Reddit entities. The Subreddit component acts as a central hub for community-specific interactions, enabling the creation and retrieval of Submission objects. Submission objects, in turn, manage post data and facilitate interactions with Comment threads. Both Submission and Comment leverage the VotableMixin for consistent voting functionality, demonstrating effective code reuse through inheritance. User-centric operations are handled by the Redditor component, which is involved in Modmail conversations. Modmail itself is composed by Subreddit, indicating its role in community moderation. LiveThread and WikiPage represent distinct content streams and informational pages, with WikiPage being directly associated with a Subreddit. This design emphasizes a clear separation of concerns, with each component encapsulating specific Reddit functionality and interacting through well-defined relationships to manage and present Reddit data. - -Subreddit -^^^^^^^^^ - -Manages subreddit data, submissions, moderation, flair, and style. It acts as a primary facade for subreddit-specific API calls, allowing users to interact with a community's content and settings. - -**Related Classes/Methods**: - -* `praw.models.reddit.subreddit.Subreddit `_ - -Submission -^^^^^^^^^^ - -Encapsulates Reddit post data, including content, flair, and moderation status. It provides methods for retrieving content and interacting with the post (e.g., voting, commenting). - -**Related Classes/Methods**: - -* `praw.models.reddit.submission.Submission `_ - -Comment -^^^^^^^ - -Manages individual comment data, including its content, author, and hierarchical position within a discussion. It provides methods for moderation and navigating comment threads. - -**Related Classes/Methods**: - -* `Comment:582-596 `_ - -Redditor -^^^^^^^^ - -Provides access to user-specific information, including profile details, submitted content, and comments. It enables interactions related to a specific Reddit user. - -**Related Classes/Methods**: - -* `Redditor:810-819 `_ - -VotableMixin -^^^^^^^^^^^^ - -A mixin class that provides common voting functionality (upvote, downvote, clear vote) to any Reddit entity that can be voted on. This promotes code reuse and consistency across votable models. - -**Related Classes/Methods**: - -* `VotableMixin:8-92 `_ - -Modmail -^^^^^^^ - -Represents a modmail conversation, facilitating communication between moderators and users, or between moderators themselves. It encapsulates messages and conversation states. - -**Related Classes/Methods**: - -* `Modmail:2627-2639 `_ - -LiveThread -^^^^^^^^^^ - -Manages data and interactions for Reddit Live Threads, which are real-time, event-driven content streams. It provides access to updates and thread metadata. - -**Related Classes/Methods**: - -* `LiveThread:261-471 `_ - -WikiPage -^^^^^^^^ - -Abstracts the content and moderation aspects of a Reddit Wiki Page. It allows for retrieval, editing, and management of wiki content within a subreddit. - -**Related Classes/Methods**: - -* `WikiPage:146-314 `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/docs/architecture_overview/overview.rst b/docs/architecture_overview/overview.rst deleted file mode 100644 index 66ccf0d12..000000000 --- a/docs/architecture_overview/overview.rst +++ /dev/null @@ -1,124 +0,0 @@ -Overview -======== - -.. mermaid:: - - graph LR - API_Client_Core["API Client Core"] - Configuration_Manager["Configuration Manager"] - Object_Transformation_Layer["Object Transformation Layer"] - Reddit_Data_Models["Reddit Data Models"] - Listing_Stream_Processors["Listing & Stream Processors"] - Exception_Handling["Exception Handling"] - API_Client_Core -- "uses" --> Configuration_Manager - API_Client_Core -- "sends raw responses to" --> Object_Transformation_Layer - API_Client_Core -- "reports errors to" --> Exception_Handling - Object_Transformation_Layer -- "receives raw responses from" --> API_Client_Core - Object_Transformation_Layer -- "instantiates" --> Reddit_Data_Models - Object_Transformation_Layer -- "parses errors with" --> Exception_Handling - Reddit_Data_Models -- "initiates requests via" --> API_Client_Core - Reddit_Data_Models -- "are utilized by" --> Listing_Stream_Processors - Listing_Stream_Processors -- "fetches batches via" --> API_Client_Core - Listing_Stream_Processors -- "utilizes" --> Reddit_Data_Models - Exception_Handling -- "receives errors from" --> API_Client_Core - Exception_Handling -- "receives parsed errors from" --> Object_Transformation_Layer - click API_Client_Core href "https://github.com/praw-dev/praw/blob/main/.codeboarding/API_Client_Core.html" "Details" - click Object_Transformation_Layer href "https://github.com/praw-dev/praw/blob/main/.codeboarding/Object_Transformation_Layer.html" "Details" - click Reddit_Data_Models href "https://github.com/praw-dev/praw/blob/main/.codeboarding/Reddit_Data_Models.html" "Details" - click Listing_Stream_Processors href "https://github.com/praw-dev/praw/blob/main/.codeboarding/Listing_Stream_Processors.html" "Details" - click Exception_Handling href "https://github.com/praw-dev/praw/blob/main/.codeboarding/Exception_Handling.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 architecture is designed as a robust API wrapper, providing an object-oriented interface to the Reddit API. It centers around the `API Client Core`, which orchestrates all network interactions, leveraging the `Configuration Manager` for settings and delegating raw response processing to the `Object Transformation Layer`. This layer is responsible for mapping raw API data into rich `Reddit Data Models`, which encapsulate Reddit entities and their behaviors. For handling collections and real-time data, the `Listing & Stream Processors` work in conjunction with the `API Client Core` and `Reddit Data Models`. Critical to its reliability, the `Exception Handling` component provides structured error reporting across the system. This design ensures a clear separation of concerns, facilitating maintainability, extensibility, and a developer-friendly experience, making it ideal for both documentation and visual flow graph representation. - -API Client Core -^^^^^^^^^^^^^^^ - -:ref:`Expand ` - -The central orchestrator for all interactions with the Reddit API, managing HTTP requests, authentication, and rate limiting. - -**Related Classes/Methods**: - -* `praw.reddit.Reddit.__init__ `_ -* `praw.reddit.Reddit.request `_ -* `praw.reddit.Reddit._objectify_request `_ -* `praw.reddit.Reddit._handle_rate_limit `_ - -Configuration Manager -^^^^^^^^^^^^^^^^^^^^^ - -Handles the loading, storage, and provision of PRAW's operational settings, including API credentials and user agent strings. - -**Related Classes/Methods**: - -* `praw.config.Config.__init__ `_ -* `praw.config.Config._load_config `_ - -Object Transformation Layer -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:ref:`Expand ` - -Acts as a data mapper, converting raw JSON responses from the Reddit API into rich, object-oriented Python representations (`Reddit Data Models`). - -**Related Classes/Methods**: - -* `praw.objector.Objector.objectify `_ -* `praw.objector.Objector.check_error `_ - -Reddit Data Models -^^^^^^^^^^^^^^^^^^ - -:ref:`Expand ` - -A comprehensive set of classes representing various Reddit entities (e.g., `Subreddit`, `Submission`, `Comment`, `Redditor`). These models encapsulate data and provide high-level methods for interacting with their respective API endpoints. - -**Related Classes/Methods**: - -* `praw.models.reddit.subreddit.Subreddit.submit `_ -* `praw.models.reddit.submission.Submission._fetch_data `_ -* `praw.models.reddit.comment.Comment.parent `_ -* `praw.models.reddit.redditor.Redditor._fetch_info `_ -* `praw.models.reddit.mixins.votable.VotableMixin._vote `_ - -Listing & Stream Processors -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:ref:`Expand ` - -Provides mechanisms for iterating through paginated API responses (listings) and consuming real-time data streams from Reddit, handling pagination logic and item uniqueness. - -**Related Classes/Methods**: - -* `praw.models.listing.generator.ListingGenerator.__next__ `_ -* `praw.models.listing.generator.ListingGenerator._next_batch `_ - -Exception Handling -^^^^^^^^^^^^^^^^^^ - -:ref:`Expand ` - -Defines a hierarchy of custom exception classes specific to PRAW and provides utilities to translate raw API error messages into structured exceptions. - -**Related Classes/Methods**: - -* `praw.exceptions.PRAWException:14-15 `_ -* `praw.exceptions.parse_exception_list:173-189 `_ - - -FAQ ---- - -`See the FAQ `_ From b55cb541b54f74066f99b8927159879f53f86fdd Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Mon, 1 Sep 2025 19:04:39 +0000 Subject: [PATCH 11/23] docs: update codeboarding documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 📚 Documentation Update This commit contains updated documentation files fetched from the CodeBoarding service. ### 📊 Summary - Documentation files created/updated: 6 - JSON files created/updated: 7 - Documentation directory: .codeboarding/ - JSON directory: .codeboarding/ - Output format: .rst - Repository analyzed: https://github.com/CodeBoarding/praw - Source branch: main - Target branch: main 🤖 This commit was automatically generated by the CodeBoarding documentation update workflow. --- .codeboarding/API_Client_Core.json | 196 +++++++++++++++++++++ .codeboarding/API_Client_Core.rst | 123 +++++++++++++ .codeboarding/API_Interaction_Facades.json | 158 +++++++++++++++++ .codeboarding/API_Interaction_Facades.rst | 108 ++++++++++++ .codeboarding/Configuration_Manager.json | 174 ++++++++++++++++++ .codeboarding/Configuration_Manager.rst | 90 ++++++++++ .codeboarding/Object_Hydrator.json | 68 +++++++ .codeboarding/Object_Hydrator.rst | 60 +++++++ .codeboarding/Reddit_Data_Models.json | 166 +++++++++++++++++ .codeboarding/Reddit_Data_Models.rst | 117 ++++++++++++ .codeboarding/analysis.json | 176 ++++++++++++++++++ .codeboarding/codeboarding_version.json | 4 + .codeboarding/overview.rst | 114 ++++++++++++ 13 files changed, 1554 insertions(+) create mode 100644 .codeboarding/API_Client_Core.json create mode 100644 .codeboarding/API_Client_Core.rst create mode 100644 .codeboarding/API_Interaction_Facades.json create mode 100644 .codeboarding/API_Interaction_Facades.rst create mode 100644 .codeboarding/Configuration_Manager.json create mode 100644 .codeboarding/Configuration_Manager.rst create mode 100644 .codeboarding/Object_Hydrator.json create mode 100644 .codeboarding/Object_Hydrator.rst create mode 100644 .codeboarding/Reddit_Data_Models.json create mode 100644 .codeboarding/Reddit_Data_Models.rst create mode 100644 .codeboarding/analysis.json create mode 100644 .codeboarding/codeboarding_version.json create mode 100644 .codeboarding/overview.rst diff --git a/.codeboarding/API_Client_Core.json b/.codeboarding/API_Client_Core.json new file mode 100644 index 000000000..3e37e378f --- /dev/null +++ b/.codeboarding/API_Client_Core.json @@ -0,0 +1,196 @@ +{ + "description": "The PRAW client subsystem provides a high-level, Pythonic interface for interacting with the Reddit API. At its core, the Reddit Client acts as a facade, orchestrating API requests and managing the overall session. It leverages Prawcore Integration for secure, low-level HTTP communication and authentication. All API interactions are routed through the Request Handler, which executes requests, processes raw responses, and applies Rate Limiting Mechanism to ensure API compliance. The raw API data is then transformed into rich Python objects by the Object Preparation component. Users interact with specific Reddit resources through Resource Accessors, which in turn utilize the Object Generator for handling collections and paginated results. The Asynchronous Operations Manager ensures proper behavior within asynchronous environments, influencing how requests are handled and resources are accessed. This architecture ensures a robust, user-friendly, and compliant interaction with the Reddit platform.", + "components": [ + { + "name": "Reddit Client", + "description": "Acts as the primary entry point and facade for all Reddit API interactions, orchestrating the setup and coordination of other components, and managing the overall API session.", + "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 + } + ], + "can_expand": true + }, + { + "name": "Prawcore Integration", + "description": "Manages the low-level HTTP communication and authentication with the Reddit API, handling token acquisition, refreshing, and secure credential management. This component's direct source code from `prawcore` could not be retrieved. Its role is inferred from its initialization and usage within the `Reddit` client.", + "referenced_source_code": [ + { + "qualified_name": "praw.reddit.Reddit._prepare_prawcore", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 700, + "reference_end_line": 730 + } + ], + "can_expand": true + }, + { + "name": "Request Handler", + "description": "Executes the actual HTTP requests to the Reddit API and processes the raw responses, transforming raw API data into structured Python objects.", + "referenced_source_code": [ + { + "qualified_name": "praw.reddit.Reddit.request", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 860, + "reference_end_line": 901 + } + ], + "can_expand": true + }, + { + "name": "Rate Limiting Mechanism", + "description": "Enforces Reddit API rate limits to ensure compliance and prevent the client from being temporarily blocked.", + "referenced_source_code": [ + { + "qualified_name": "praw.reddit.Reddit._handle_rate_limit", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 649, + "reference_end_line": 666 + } + ], + "can_expand": false + }, + { + "name": "Object Preparation", + "description": "Configures the mechanism for converting raw JSON responses from the Reddit API into rich, type-safe PRAW Python objects.", + "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 + } + ], + "can_expand": true + }, + { + "name": "Resource Accessors", + "description": "Provides a Pythonic interface for interacting with specific Reddit API endpoints and resources (e.g., fetching comments, submitting posts).", + "referenced_source_code": [ + { + "qualified_name": "praw.reddit.Reddit.get", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 790, + "reference_end_line": 797 + } + ], + "can_expand": true + }, + { + "name": "Object Generator", + "description": "Facilitates the retrieval and iteration of collections of Reddit objects (e.g., lists of submissions or comments), often used for paginated results.", + "referenced_source_code": [ + { + "qualified_name": "praw.models.listing.generator.ListingGenerator", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py", + "reference_start_line": 17, + "reference_end_line": 103 + } + ], + "can_expand": true + }, + { + "name": "Asynchronous Operations Manager", + "description": "Determines and manages the asynchronous nature of API requests, integrating with Python's `asyncio`.", + "referenced_source_code": [ + { + "qualified_name": "praw.reddit.Reddit._check_for_async", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 609, + "reference_end_line": 630 + } + ], + "can_expand": true + } + ], + "components_relations": [ + { + "relation": "Initializes and configures", + "src_name": "Reddit Client", + "dst_name": "Prawcore Integration" + }, + { + "relation": "Delegates API calls to", + "src_name": "Reddit Client", + "dst_name": "Request Handler" + }, + { + "relation": "Initializes", + "src_name": "Reddit Client", + "dst_name": "Object Preparation" + }, + { + "relation": "Provides services to", + "src_name": "Prawcore Integration", + "dst_name": "Request Handler" + }, + { + "relation": "Queries", + "src_name": "Request Handler", + "dst_name": "Asynchronous Operations Manager" + }, + { + "relation": "Uses", + "src_name": "Request Handler", + "dst_name": "Object Preparation" + }, + { + "relation": "Relies on", + "src_name": "Request Handler", + "dst_name": "Prawcore Integration" + }, + { + "relation": "Is influenced by", + "src_name": "Request Handler", + "dst_name": "Rate Limiting Mechanism" + }, + { + "relation": "Enforces restrictions on", + "src_name": "Rate Limiting Mechanism", + "dst_name": "Request Handler" + }, + { + "relation": "Is consulted by", + "src_name": "Rate Limiting Mechanism", + "dst_name": "Resource Accessors" + }, + { + "relation": "Converts data for", + "src_name": "Object Preparation", + "dst_name": "Request Handler" + }, + { + "relation": "Sends API requests to", + "src_name": "Resource Accessors", + "dst_name": "Request Handler" + }, + { + "relation": "Leverages", + "src_name": "Resource Accessors", + "dst_name": "Object Generator" + }, + { + "relation": "Is influenced by", + "src_name": "Resource Accessors", + "dst_name": "Asynchronous Operations Manager" + }, + { + "relation": "Provides sequences of objects to", + "src_name": "Object Generator", + "dst_name": "Resource Accessors" + }, + { + "relation": "Informs", + "src_name": "Asynchronous Operations Manager", + "dst_name": "Request Handler" + }, + { + "relation": "Influences", + "src_name": "Asynchronous Operations Manager", + "dst_name": "Resource Accessors" + } + ] +} diff --git a/.codeboarding/API_Client_Core.rst b/.codeboarding/API_Client_Core.rst new file mode 100644 index 000000000..403dce5e0 --- /dev/null +++ b/.codeboarding/API_Client_Core.rst @@ -0,0 +1,123 @@ +Api Client Core +=============== + +.. mermaid:: + + graph LR + Reddit_Client["Reddit Client"] + Prawcore_Integration["Prawcore Integration"] + Request_Handler["Request Handler"] + Rate_Limiting_Mechanism["Rate Limiting Mechanism"] + Object_Preparation["Object Preparation"] + Resource_Accessors["Resource Accessors"] + Object_Generator["Object Generator"] + Asynchronous_Operations_Manager["Asynchronous Operations Manager"] + Reddit_Client -- "Initializes and configures" --> Prawcore_Integration + Reddit_Client -- "Delegates API calls to" --> Request_Handler + Reddit_Client -- "Initializes" --> Object_Preparation + Prawcore_Integration -- "Provides services to" --> Request_Handler + Request_Handler -- "Queries" --> Asynchronous_Operations_Manager + Request_Handler -- "Uses" --> Object_Preparation + Request_Handler -- "Relies on" --> Prawcore_Integration + Request_Handler -- "Is influenced by" --> Rate_Limiting_Mechanism + Rate_Limiting_Mechanism -- "Enforces restrictions on" --> Request_Handler + Rate_Limiting_Mechanism -- "Is consulted by" --> Resource_Accessors + Object_Preparation -- "Converts data for" --> Request_Handler + Resource_Accessors -- "Sends API requests to" --> Request_Handler + Resource_Accessors -- "Leverages" --> Object_Generator + Resource_Accessors -- "Is influenced by" --> Asynchronous_Operations_Manager + Object_Generator -- "Provides sequences of objects to" --> Resource_Accessors + Asynchronous_Operations_Manager -- "Informs" --> Request_Handler + Asynchronous_Operations_Manager -- "Influences" --> Resource_Accessors + +| |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 client subsystem provides a high-level, Pythonic interface for interacting with the Reddit API. At its core, the Reddit Client acts as a facade, orchestrating API requests and managing the overall session. It leverages Prawcore Integration for secure, low-level HTTP communication and authentication. All API interactions are routed through the Request Handler, which executes requests, processes raw responses, and applies Rate Limiting Mechanism to ensure API compliance. The raw API data is then transformed into rich Python objects by the Object Preparation component. Users interact with specific Reddit resources through Resource Accessors, which in turn utilize the Object Generator for handling collections and paginated results. The Asynchronous Operations Manager ensures proper behavior within asynchronous environments, influencing how requests are handled and resources are accessed. This architecture ensures a robust, user-friendly, and compliant interaction with the Reddit platform. + +Reddit Client +^^^^^^^^^^^^^ + +Acts as the primary entry point and facade for all Reddit API interactions, orchestrating the setup and coordination of other components, and managing the overall API session. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit:57-901 `_ + +Prawcore Integration +^^^^^^^^^^^^^^^^^^^^ + +Manages the low-level HTTP communication and authentication with the Reddit API, handling token acquisition, refreshing, and secure credential management. This component's direct source code from `prawcore` could not be retrieved. Its role is inferred from its initialization and usage within the `Reddit` client. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit._prepare_prawcore:700-730 `_ + +Request Handler +^^^^^^^^^^^^^^^ + +Executes the actual HTTP requests to the Reddit API and processes the raw responses, transforming raw API data into structured Python objects. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit.request:860-901 `_ + +Rate Limiting Mechanism +^^^^^^^^^^^^^^^^^^^^^^^ + +Enforces Reddit API rate limits to ensure compliance and prevent the client from being temporarily blocked. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit._handle_rate_limit:649-666 `_ + +Object Preparation +^^^^^^^^^^^^^^^^^^ + +Configures the mechanism for converting raw JSON responses from the Reddit API into rich, type-safe PRAW Python objects. + +**Related Classes/Methods**: + +* `praw.objector.Objector:17-263 `_ + +Resource Accessors +^^^^^^^^^^^^^^^^^^ + +Provides a Pythonic interface for interacting with specific Reddit API endpoints and resources (e.g., fetching comments, submitting posts). + +**Related Classes/Methods**: + +* `praw.reddit.Reddit.get:790-797 `_ + +Object Generator +^^^^^^^^^^^^^^^^ + +Facilitates the retrieval and iteration of collections of Reddit objects (e.g., lists of submissions or comments), often used for paginated results. + +**Related Classes/Methods**: + +* `praw.models.listing.generator.ListingGenerator:17-103 `_ + +Asynchronous Operations Manager +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Determines and manages the asynchronous nature of API requests, integrating with Python's `asyncio`. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit._check_for_async:609-630 `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/.codeboarding/API_Interaction_Facades.json b/.codeboarding/API_Interaction_Facades.json new file mode 100644 index 000000000..7333d2c7b --- /dev/null +++ b/.codeboarding/API_Interaction_Facades.json @@ -0,0 +1,158 @@ +{ + "description": "The `API Interaction Facades` subsystem encompasses high-level, domain-specific interfaces for interacting with the Reddit API. It abstracts complex operations and data retrieval patterns, grouping functionalities related to listing/streaming, subreddit management, moderation tools, and user/authentication specific actions.", + "components": [ + { + "name": "Subreddit", + "description": "Primary facade for all subreddit-related operations, including content submission, moderation, flair management, appearance customization, and data retrieval. It provides a high-level interface for interacting with a specific subreddit.", + "referenced_source_code": [ + { + "qualified_name": "praw.models.reddit.subreddit.Subreddit", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/subreddit.py", + "reference_start_line": 2446, + "reference_end_line": 2446 + } + ], + "can_expand": true + }, + { + "name": "Redditor", + "description": "Represents a Reddit user and provides methods for user-specific actions such as profile interaction, friendship management, and accessing user-generated content (submissions, comments).", + "referenced_source_code": [ + { + "qualified_name": "praw.models.reddit.redditor.Redditor", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/redditor.py", + "reference_start_line": 421, + "reference_end_line": 421 + } + ], + "can_expand": true + }, + { + "name": "Modmail", + "description": "Manages modmail conversations within a specific subreddit, enabling functionalities like reading, replying to, and managing modmail threads.", + "referenced_source_code": [ + { + "qualified_name": "praw.models.reddit.modmail.Modmail", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/modmail.py", + "reference_start_line": 1, + "reference_end_line": 1 + } + ], + "can_expand": false + }, + { + "name": "ModNotes", + "description": "Facilitates the creation, retrieval, and deletion of moderator notes associated with various Reddit entities (e.g., users, submissions).", + "referenced_source_code": [ + { + "qualified_name": "praw.models.mod_notes.ModNotes", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/mod_notes.py", + "reference_start_line": 1, + "reference_end_line": 1 + } + ], + "can_expand": true + }, + { + "name": "Auth", + "description": "Manages the authentication and authorization processes with the Reddit API, ensuring all outgoing requests are properly credentialed and secure.", + "referenced_source_code": [ + { + "qualified_name": "praw.models.auth.Auth", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/auth.py", + "reference_start_line": 11, + "reference_end_line": 125 + } + ], + "can_expand": true + }, + { + "name": "ListingGenerator", + "description": "Provides an iterable interface for fetching paginated data from various Reddit API endpoints, handling the underlying pagination logic transparently.", + "referenced_source_code": [ + { + "qualified_name": "praw.models.listing.generator.ListingGenerator", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py", + "reference_start_line": 17, + "reference_end_line": 103 + } + ], + "can_expand": true + }, + { + "name": "stream_generator", + "description": "Offers a resilient and generic streaming mechanism for continuous data retrieval from Reddit, incorporating features like rate limiting, duplicate detection, and exponential backoff for robust operation.", + "referenced_source_code": [ + { + "qualified_name": "praw.models.util.stream_generator", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/util.py", + "reference_start_line": 36, + "reference_end_line": 163 + } + ], + "can_expand": true + } + ], + "components_relations": [ + { + "relation": "delegates to", + "src_name": "Subreddit", + "dst_name": "Modmail" + }, + { + "relation": "interacts with", + "src_name": "Subreddit", + "dst_name": "ModNotes" + }, + { + "relation": "utilizes", + "src_name": "Subreddit", + "dst_name": "ListingGenerator" + }, + { + "relation": "leverages", + "src_name": "Subreddit", + "dst_name": "stream_generator" + }, + { + "relation": "relies on", + "src_name": "Subreddit", + "dst_name": "Auth" + }, + { + "relation": "utilizes", + "src_name": "Redditor", + "dst_name": "ListingGenerator" + }, + { + "relation": "leverages", + "src_name": "Redditor", + "dst_name": "stream_generator" + }, + { + "relation": "relies on", + "src_name": "Redditor", + "dst_name": "Auth" + }, + { + "relation": "relies on", + "src_name": "Modmail", + "dst_name": "Auth" + }, + { + "relation": "relies on", + "src_name": "ModNotes", + "dst_name": "Auth" + }, + { + "relation": "relies on", + "src_name": "ListingGenerator", + "dst_name": "Auth" + }, + { + "relation": "relies on", + "src_name": "stream_generator", + "dst_name": "Auth" + } + ] +} diff --git a/.codeboarding/API_Interaction_Facades.rst b/.codeboarding/API_Interaction_Facades.rst new file mode 100644 index 000000000..f3214d09f --- /dev/null +++ b/.codeboarding/API_Interaction_Facades.rst @@ -0,0 +1,108 @@ +Api Interaction Facades +======================= + +.. mermaid:: + + graph LR + Subreddit["Subreddit"] + Redditor["Redditor"] + Modmail["Modmail"] + ModNotes["ModNotes"] + Auth["Auth"] + ListingGenerator["ListingGenerator"] + stream_generator["stream_generator"] + Subreddit -- "delegates to" --> Modmail + Subreddit -- "interacts with" --> ModNotes + Subreddit -- "utilizes" --> ListingGenerator + Subreddit -- "leverages" --> stream_generator + Subreddit -- "relies on" --> Auth + Redditor -- "utilizes" --> ListingGenerator + Redditor -- "leverages" --> stream_generator + Redditor -- "relies on" --> Auth + Modmail -- "relies on" --> Auth + ModNotes -- "relies on" --> Auth + ListingGenerator -- "relies on" --> Auth + stream_generator -- "relies on" --> Auth + +| |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 `API Interaction Facades` subsystem encompasses high-level, domain-specific interfaces for interacting with the Reddit API. It abstracts complex operations and data retrieval patterns, grouping functionalities related to listing/streaming, subreddit management, moderation tools, and user/authentication specific actions. + +Subreddit +^^^^^^^^^ + +Primary facade for all subreddit-related operations, including content submission, moderation, flair management, appearance customization, and data retrieval. It provides a high-level interface for interacting with a specific subreddit. + +**Related Classes/Methods**: + +* `praw.models.reddit.subreddit.Subreddit `_ + +Redditor +^^^^^^^^ + +Represents a Reddit user and provides methods for user-specific actions such as profile interaction, friendship management, and accessing user-generated content (submissions, comments). + +**Related Classes/Methods**: + +* `praw.models.reddit.redditor.Redditor `_ + +Modmail +^^^^^^^ + +Manages modmail conversations within a specific subreddit, enabling functionalities like reading, replying to, and managing modmail threads. + +**Related Classes/Methods**: + +* `praw.models.reddit.modmail.Modmail `_ + +ModNotes +^^^^^^^^ + +Facilitates the creation, retrieval, and deletion of moderator notes associated with various Reddit entities (e.g., users, submissions). + +**Related Classes/Methods**: + +* `praw.models.mod_notes.ModNotes `_ + +Auth +^^^^ + +Manages the authentication and authorization processes with the Reddit API, ensuring all outgoing requests are properly credentialed and secure. + +**Related Classes/Methods**: + +* `praw.models.auth.Auth:11-125 `_ + +ListingGenerator +^^^^^^^^^^^^^^^^ + +Provides an iterable interface for fetching paginated data from various Reddit API endpoints, handling the underlying pagination logic transparently. + +**Related Classes/Methods**: + +* `praw.models.listing.generator.ListingGenerator:17-103 `_ + +stream_generator +^^^^^^^^^^^^^^^^ + +Offers a resilient and generic streaming mechanism for continuous data retrieval from Reddit, incorporating features like rate limiting, duplicate detection, and exponential backoff for robust operation. + +**Related Classes/Methods**: + +* `praw.models.util.stream_generator:36-163 `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/.codeboarding/Configuration_Manager.json b/.codeboarding/Configuration_Manager.json new file mode 100644 index 000000000..f0943c1e1 --- /dev/null +++ b/.codeboarding/Configuration_Manager.json @@ -0,0 +1,174 @@ +{ + "description": "The PRAW library's core subsystem is designed around a clear separation of concerns, enabling robust and flexible interaction with the Reddit API. At its heart, the `Reddit` class acts as the central orchestrator, coordinating various specialized components for configuration, API communication, authentication, and response processing. This architecture ensures that PRAW can adapt to different environments and authentication schemes while providing a consistent and intuitive interface for developers.", + "components": [ + { + "name": "Reddit API Interface", + "description": "The primary entry point for developers to interact with the Reddit API. It initializes and manages the lifecycle of other core components, providing high-level methods for accessing 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 + } + ], + "can_expand": true + }, + { + "name": "Configuration Manager", + "description": "This component centralizes and manages all configuration settings required by the PRAW library. It handles reading configurations from external files (like `praw.ini`) and environment variables, applying default values, and making these settings available throughout the application.", + "referenced_source_code": [ + { + "qualified_name": "praw.config.Config", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/config.py", + "reference_start_line": 52, + "reference_end_line": 52 + }, + { + "qualified_name": "praw.ini", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/praw.ini", + "reference_start_line": 1, + "reference_end_line": 1 + }, + { + "qualified_name": "os.getenv", + "reference_file": null, + "reference_start_line": 1, + "reference_end_line": 1 + } + ], + "can_expand": false + }, + { + "name": "API Client/Connector (Prawcore Requestor)", + "description": "Responsible for executing the actual HTTP requests to the Reddit API. It utilizes the base URL and user agent provided by the configuration and handles the low-level network communication. This component is part of the `prawcore` library, a core dependency of PRAW.", + "referenced_source_code": [ + { + "qualified_name": "prawcore.requestor.Requestor", + "reference_file": null, + "reference_start_line": 1, + "reference_end_line": 1 + } + ], + "can_expand": true + }, + { + "name": "Authentication Module", + "description": "Manages the various authentication flows required to interact with the Reddit API. It uses credentials (client ID, client secret, redirect URI) from the configuration to establish and maintain authenticated sessions.", + "referenced_source_code": [ + { + "qualified_name": "praw.models.Auth", + "reference_file": null, + "reference_start_line": 1, + "reference_end_line": 1 + }, + { + "qualified_name": "prawcore.auth.TrustedAuthenticator", + "reference_file": null, + "reference_start_line": 1, + "reference_end_line": 1 + }, + { + "qualified_name": "prawcore.auth.UntrustedAuthenticator", + "reference_file": null, + "reference_start_line": 1, + "reference_end_line": 1 + }, + { + "qualified_name": "prawcore.auth.ReadOnlyAuthorizer", + "reference_file": null, + "reference_start_line": 1, + "reference_end_line": 1 + }, + { + "qualified_name": "prawcore.auth.ScriptAuthorizer", + "reference_file": null, + "reference_start_line": 1, + "reference_end_line": 1 + }, + { + "qualified_name": "prawcore.auth.DeviceIDAuthorizer", + "reference_file": null, + "reference_start_line": 1, + "reference_end_line": 1 + } + ], + "can_expand": true + }, + { + "name": "Response Objector", + "description": "Processes raw JSON responses received from the Reddit API, transforming them into structured PRAW-specific Python objects (e.g., `Comment`, `Submission`, `Redditor`). It also handles the parsing of API-specific errors.", + "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 + } + ], + "can_expand": true + } + ], + "components_relations": [ + { + "relation": "Initializes and uses", + "src_name": "Reddit API Interface", + "dst_name": "Configuration Manager" + }, + { + "relation": "Initializes and uses", + "src_name": "Reddit API Interface", + "dst_name": "API Client/Connector (Prawcore Requestor)" + }, + { + "relation": "Initializes and uses", + "src_name": "Reddit API Interface", + "dst_name": "Authentication Module" + }, + { + "relation": "Initializes and uses", + "src_name": "Reddit API Interface", + "dst_name": "Response Objector" + }, + { + "relation": "Provides configuration to", + "src_name": "Configuration Manager", + "dst_name": "Reddit API Interface" + }, + { + "relation": "sends requests to", + "src_name": "Reddit API Interface", + "dst_name": "API Client/Connector (Prawcore Requestor)" + }, + { + "relation": "Provides authentication parameters to", + "src_name": "Configuration Manager", + "dst_name": "Authentication Module" + }, + { + "relation": "authenticates requests for", + "src_name": "Authentication Module", + "dst_name": "API Client/Connector (Prawcore Requestor)" + }, + { + "relation": "returns raw data to", + "src_name": "API Client/Connector (Prawcore Requestor)", + "dst_name": "Response Objector" + }, + { + "relation": "Returns PRAW objects to", + "src_name": "Response Objector", + "dst_name": "Reddit API Interface" + }, + { + "relation": "configures", + "src_name": "Reddit API Interface", + "dst_name": "Authentication Module" + }, + { + "relation": "configures", + "src_name": "Reddit API Interface", + "dst_name": "API Client/Connector (Prawcore Requestor)" + } + ] +} diff --git a/.codeboarding/Configuration_Manager.rst b/.codeboarding/Configuration_Manager.rst new file mode 100644 index 000000000..cfa734acf --- /dev/null +++ b/.codeboarding/Configuration_Manager.rst @@ -0,0 +1,90 @@ +Configuration Manager +===================== + +.. mermaid:: + + graph LR + Reddit_API_Interface["Reddit API Interface"] + Configuration_Manager["Configuration Manager"] + API_Client_Connector_Prawcore_Requestor_["API Client/Connector (Prawcore Requestor)"] + Authentication_Module["Authentication Module"] + Response_Objector["Response Objector"] + Reddit_API_Interface -- "Initializes and uses" --> Configuration_Manager + Reddit_API_Interface -- "Initializes and uses" --> API_Client_Connector_Prawcore_Requestor_ + Reddit_API_Interface -- "Initializes and uses" --> Authentication_Module + Reddit_API_Interface -- "Initializes and uses" --> Response_Objector + Configuration_Manager -- "Provides configuration to" --> Reddit_API_Interface + Reddit_API_Interface -- "sends requests to" --> API_Client_Connector_Prawcore_Requestor_ + Configuration_Manager -- "Provides authentication parameters to" --> Authentication_Module + Authentication_Module -- "authenticates requests for" --> API_Client_Connector_Prawcore_Requestor_ + API_Client_Connector_Prawcore_Requestor_ -- "returns raw data to" --> Response_Objector + Response_Objector -- "Returns PRAW objects to" --> Reddit_API_Interface + Reddit_API_Interface -- "configures" --> Authentication_Module + Reddit_API_Interface -- "configures" --> API_Client_Connector_Prawcore_Requestor_ + 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 subsystem is designed around a clear separation of concerns, enabling robust and flexible interaction with the Reddit API. At its heart, the `Reddit` class acts as the central orchestrator, coordinating various specialized components for configuration, API communication, authentication, and response processing. This architecture ensures that PRAW can adapt to different environments and authentication schemes while providing a consistent and intuitive interface for developers. + +Reddit API Interface +^^^^^^^^^^^^^^^^^^^^ + +The primary entry point for developers to interact with the Reddit API. It initializes and manages the lifecycle of other core components, providing high-level methods for accessing Reddit resources. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit:57-901 `_ + +Configuration Manager +^^^^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +This component centralizes and manages all configuration settings required by the PRAW library. It handles reading configurations from external files (like `praw.ini`) and environment variables, applying default values, and making these settings available throughout the application. + +**Related Classes/Methods**: + +* `praw.config.Config `_ +* `praw.ini `_ + +API Client/Connector (Prawcore Requestor) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Responsible for executing the actual HTTP requests to the Reddit API. It utilizes the base URL and user agent provided by the configuration and handles the low-level network communication. This component is part of the `prawcore` library, a core dependency of PRAW. + +**Related Classes/Methods**: + + +Authentication Module +^^^^^^^^^^^^^^^^^^^^^ + +Manages the various authentication flows required to interact with the Reddit API. It uses credentials (client ID, client secret, redirect URI) from the configuration to establish and maintain authenticated sessions. + +**Related Classes/Methods**: + + +Response Objector +^^^^^^^^^^^^^^^^^ + +Processes raw JSON responses received from the Reddit API, transforming them into structured PRAW-specific Python objects (e.g., `Comment`, `Submission`, `Redditor`). It also handles the parsing of API-specific errors. + +**Related Classes/Methods**: + +* `praw.objector.Objector:17-263 `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/.codeboarding/Object_Hydrator.json b/.codeboarding/Object_Hydrator.json new file mode 100644 index 000000000..ec937306a --- /dev/null +++ b/.codeboarding/Object_Hydrator.json @@ -0,0 +1,68 @@ +{ + "description": "The PRAW library's core functionality revolves around three main components: praw.Reddit (API Client), Objector, and PRAW Data Models. The praw.Reddit (API Client) serves as the primary interface for making requests to the Reddit API and receiving raw JSON responses. These raw responses are then passed to the Objector, which acts as a central factory and dispatcher. The Objector is responsible for parsing the JSON data, handling any API errors, and transforming the raw data into rich, interactive PRAW Data Models. These data models, such as Submission, Comment, and Redditor, encapsulate Reddit resources and provide a Pythonic way to interact with them, abstracting the underlying API complexities. This architecture ensures a clear separation of concerns, with the API client handling communication, the Objector managing data hydration, and the data models representing the structured Reddit resources.", + "components": [ + { + "name": "Objector", + "description": "The core component of the hydration process. It acts as a factory and dispatcher, orchestrating the conversion of raw JSON data from the Reddit API into rich PRAW model objects. It also handles error detection and parsing within the API response.", + "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 + } + ], + "can_expand": true + }, + { + "name": "praw.Reddit (API Client)", + "description": "This component represents the main entry point for interacting with the Reddit API. It is responsible for making HTTP requests, receiving raw JSON responses, and then delegating the processing of these responses to the Objector to convert them into PRAW models.", + "referenced_source_code": [ + { + "qualified_name": "praw.Reddit", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/__init__.py", + "reference_start_line": 13, + "reference_end_line": 13 + } + ], + "can_expand": true + }, + { + "name": "PRAW Data Models", + "description": "These are the rich, interactive Python objects that represent various Reddit resources (e.g., submissions, comments, users). They encapsulate the data and provide methods for interacting with those resources in a Pythonic way, abstracting the underlying API calls.", + "referenced_source_code": [ + { + "qualified_name": "praw.models.submission.Submission", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/submission.py", + "reference_start_line": 0, + "reference_end_line": 0 + }, + { + "qualified_name": "praw.models.comment.Comment", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/comment.py", + "reference_start_line": 0, + "reference_end_line": 0 + }, + { + "qualified_name": "praw.models.redditor.Redditor", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/redditor.py", + "reference_start_line": 0, + "reference_end_line": 0 + } + ], + "can_expand": true + } + ], + "components_relations": [ + { + "relation": "passes raw API responses to and depends on", + "src_name": "praw.Reddit (API Client)", + "dst_name": "Objector" + }, + { + "relation": "creates instances of", + "src_name": "Objector", + "dst_name": "PRAW Data Models" + } + ] +} diff --git a/.codeboarding/Object_Hydrator.rst b/.codeboarding/Object_Hydrator.rst new file mode 100644 index 000000000..a85b8a27a --- /dev/null +++ b/.codeboarding/Object_Hydrator.rst @@ -0,0 +1,60 @@ +Object Hydrator +=============== + +.. mermaid:: + + graph LR + Objector["Objector"] + praw_Reddit_API_Client_["praw.Reddit (API Client)"] + PRAW_Data_Models["PRAW Data Models"] + praw_Reddit_API_Client_ -- "passes raw API responses to and depends on" --> Objector + Objector -- "creates instances of" --> PRAW_Data_Models + +| |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 functionality revolves around three main components: praw.Reddit (API Client), Objector, and PRAW Data Models. The praw.Reddit (API Client) serves as the primary interface for making requests to the Reddit API and receiving raw JSON responses. These raw responses are then passed to the Objector, which acts as a central factory and dispatcher. The Objector is responsible for parsing the JSON data, handling any API errors, and transforming the raw data into rich, interactive PRAW Data Models. These data models, such as Submission, Comment, and Redditor, encapsulate Reddit resources and provide a Pythonic way to interact with them, abstracting the underlying API complexities. This architecture ensures a clear separation of concerns, with the API client handling communication, the Objector managing data hydration, and the data models representing the structured Reddit resources. + +Objector +^^^^^^^^ + +The core component of the hydration process. It acts as a factory and dispatcher, orchestrating the conversion of raw JSON data from the Reddit API into rich PRAW model objects. It also handles error detection and parsing within the API response. + +**Related Classes/Methods**: + +* `praw.objector.Objector:17-263 `_ + +praw.Reddit (API Client) +^^^^^^^^^^^^^^^^^^^^^^^^ + +This component represents the main entry point for interacting with the Reddit API. It is responsible for making HTTP requests, receiving raw JSON responses, and then delegating the processing of these responses to the Objector to convert them into PRAW models. + +**Related Classes/Methods**: + +* `praw.Reddit `_ + +PRAW Data Models +^^^^^^^^^^^^^^^^ + +These are the rich, interactive Python objects that represent various Reddit resources (e.g., submissions, comments, users). They encapsulate the data and provide methods for interacting with those resources in a Pythonic way, abstracting the underlying API calls. + +**Related Classes/Methods**: + +* `praw.models.submission.Submission `_ +* `praw.models.comment.Comment `_ +* `praw.models.redditor.Redditor `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/.codeboarding/Reddit_Data_Models.json b/.codeboarding/Reddit_Data_Models.json new file mode 100644 index 000000000..d33dade71 --- /dev/null +++ b/.codeboarding/Reddit_Data_Models.json @@ -0,0 +1,166 @@ +{ + "description": "The PRAW `reddit.models` subsystem provides a structured object-oriented interface for interacting with the Reddit API. Core components like `Submission`, `Comment`, `Redditor`, and `Subreddit` serve as primary data models, encapsulating Reddit entities and their associated functionalities. These core models are augmented by specialized moderation components (`SubmissionModeration`, `CommentModeration`, `SubredditModeration`) that provide administrative capabilities, and stream components (`RedditorStream`) for accessing dynamic content. The system is designed around clear object relationships, where entities like `Subreddit` contain `Submission`s, and `Submission`s contain `Comment`s, facilitating intuitive navigation and interaction with Reddit data. Moderation components act directly upon their respective core entities, enabling a clear separation of concerns between data representation and administrative actions.", + "components": [ + { + "name": "Submission", + "description": "Represents a Reddit post, encapsulating its data (e.g., title, content, author, subreddit) and providing methods for interaction (e.g., voting, replying, editing). It serves as the primary interface for submission-specific data and actions.", + "referenced_source_code": [ + { + "qualified_name": "Submission", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/docs/examples/lmgtfy_bot.py", + "reference_start_line": 24, + "reference_end_line": 24 + } + ], + "can_expand": true + }, + { + "name": "Comment", + "description": "Represents a Reddit comment, managing its content, author, and position within a discussion thread. It provides methods for managing comment content and its hierarchical position.", + "referenced_source_code": [ + { + "qualified_name": "Comment", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 582, + "reference_end_line": 596 + } + ], + "can_expand": false + }, + { + "name": "Redditor", + "description": "Represents a Reddit user, offering access to their profile, activity history (e.g., submissions, comments), and relationships with other users or subreddits.", + "referenced_source_code": [ + { + "qualified_name": "Redditor", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "reference_start_line": 810, + "reference_end_line": 819 + } + ], + "can_expand": true + }, + { + "name": "Subreddit", + "description": "Represents a Reddit community, serving as a facade for managing subreddit settings, content, and user interactions within that community. It provides access to posts, moderation tools, and community-specific data.", + "referenced_source_code": [ + { + "qualified_name": "Subreddit", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/docs/examples/lmgtfy_bot.py", + "reference_start_line": 19, + "reference_end_line": 19 + } + ], + "can_expand": true + }, + { + "name": "SubmissionModeration", + "description": "Provides moderation functionalities specifically for a `Submission` object, enabling actions such as approving, removing, locking, or distinguishing posts.", + "referenced_source_code": [ + { + "qualified_name": "SubmissionModeration", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/submission.py", + "reference_start_line": 93, + "reference_end_line": 392 + } + ], + "can_expand": true + }, + { + "name": "CommentModeration", + "description": "Provides moderation functionalities specifically for a `Comment` object, enabling actions like approving, removing, or distinguishing comments.", + "referenced_source_code": [ + { + "qualified_name": "CommentModeration", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/comment.py", + "reference_start_line": 314, + "reference_end_line": 350 + } + ], + "can_expand": false + }, + { + "name": "RedditorStream", + "description": "Offers access to various streams of content related to a `Redditor`, such as their submissions, comments, or saved items, allowing for real-time or historical data retrieval.", + "referenced_source_code": [ + { + "qualified_name": "RedditorStream", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/redditor.py", + "reference_start_line": 412, + "reference_end_line": 457 + } + ], + "can_expand": false + }, + { + "name": "SubredditModeration", + "description": "Provides comprehensive moderation tools for a `Subreddit`, including managing users (e.g., banning, muting), flair, and content policies at the community level.", + "referenced_source_code": [ + { + "qualified_name": "SubredditModeration", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/user_subreddit.py", + "reference_start_line": 82, + "reference_end_line": 199 + } + ], + "can_expand": true + } + ], + "components_relations": [ + { + "relation": "contains", + "src_name": "Submission", + "dst_name": "Comment" + }, + { + "relation": "interacts with", + "src_name": "Submission", + "dst_name": "SubmissionModeration" + }, + { + "relation": "associated with", + "src_name": "Comment", + "dst_name": "Submission" + }, + { + "relation": "interacts with", + "src_name": "Comment", + "dst_name": "CommentModeration" + }, + { + "relation": "provides access to", + "src_name": "Redditor", + "dst_name": "RedditorStream" + }, + { + "relation": "contains", + "src_name": "Subreddit", + "dst_name": "Submission" + }, + { + "relation": "interacts with", + "src_name": "Subreddit", + "dst_name": "SubredditModeration" + }, + { + "relation": "acts upon", + "src_name": "SubmissionModeration", + "dst_name": "Submission" + }, + { + "relation": "acts upon", + "src_name": "CommentModeration", + "dst_name": "Comment" + }, + { + "relation": "provides data streams related to", + "src_name": "RedditorStream", + "dst_name": "Redditor" + }, + { + "relation": "acts upon", + "src_name": "SubredditModeration", + "dst_name": "Subreddit" + } + ] +} diff --git a/.codeboarding/Reddit_Data_Models.rst b/.codeboarding/Reddit_Data_Models.rst new file mode 100644 index 000000000..0ffbe344a --- /dev/null +++ b/.codeboarding/Reddit_Data_Models.rst @@ -0,0 +1,117 @@ +Reddit Data Models +================== + +.. mermaid:: + + graph LR + Submission["Submission"] + Comment["Comment"] + Redditor["Redditor"] + Subreddit["Subreddit"] + SubmissionModeration["SubmissionModeration"] + CommentModeration["CommentModeration"] + RedditorStream["RedditorStream"] + SubredditModeration["SubredditModeration"] + Submission -- "contains" --> Comment + Submission -- "interacts with" --> SubmissionModeration + Comment -- "associated with" --> Submission + Comment -- "interacts with" --> CommentModeration + Redditor -- "provides access to" --> RedditorStream + Subreddit -- "contains" --> Submission + Subreddit -- "interacts with" --> SubredditModeration + SubmissionModeration -- "acts upon" --> Submission + CommentModeration -- "acts upon" --> Comment + RedditorStream -- "provides data streams related to" --> Redditor + SubredditModeration -- "acts upon" --> Subreddit + +| |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 `reddit.models` subsystem provides a structured object-oriented interface for interacting with the Reddit API. Core components like `Submission`, `Comment`, `Redditor`, and `Subreddit` serve as primary data models, encapsulating Reddit entities and their associated functionalities. These core models are augmented by specialized moderation components (`SubmissionModeration`, `CommentModeration`, `SubredditModeration`) that provide administrative capabilities, and stream components (`RedditorStream`) for accessing dynamic content. The system is designed around clear object relationships, where entities like `Subreddit` contain `Submission`s, and `Submission`s contain `Comment`s, facilitating intuitive navigation and interaction with Reddit data. Moderation components act directly upon their respective core entities, enabling a clear separation of concerns between data representation and administrative actions. + +Submission +^^^^^^^^^^ + +Represents a Reddit post, encapsulating its data (e.g., title, content, author, subreddit) and providing methods for interaction (e.g., voting, replying, editing). It serves as the primary interface for submission-specific data and actions. + +**Related Classes/Methods**: + +* `Submission `_ + +Comment +^^^^^^^ + +Represents a Reddit comment, managing its content, author, and position within a discussion thread. It provides methods for managing comment content and its hierarchical position. + +**Related Classes/Methods**: + +* `Comment:582-596 `_ + +Redditor +^^^^^^^^ + +Represents a Reddit user, offering access to their profile, activity history (e.g., submissions, comments), and relationships with other users or subreddits. + +**Related Classes/Methods**: + +* `Redditor:810-819 `_ + +Subreddit +^^^^^^^^^ + +Represents a Reddit community, serving as a facade for managing subreddit settings, content, and user interactions within that community. It provides access to posts, moderation tools, and community-specific data. + +**Related Classes/Methods**: + +* `Subreddit `_ + +SubmissionModeration +^^^^^^^^^^^^^^^^^^^^ + +Provides moderation functionalities specifically for a `Submission` object, enabling actions such as approving, removing, locking, or distinguishing posts. + +**Related Classes/Methods**: + +* `SubmissionModeration:93-392 `_ + +CommentModeration +^^^^^^^^^^^^^^^^^ + +Provides moderation functionalities specifically for a `Comment` object, enabling actions like approving, removing, or distinguishing comments. + +**Related Classes/Methods**: + +* `CommentModeration:314-350 `_ + +RedditorStream +^^^^^^^^^^^^^^ + +Offers access to various streams of content related to a `Redditor`, such as their submissions, comments, or saved items, allowing for real-time or historical data retrieval. + +**Related Classes/Methods**: + +* `RedditorStream:412-457 `_ + +SubredditModeration +^^^^^^^^^^^^^^^^^^^ + +Provides comprehensive moderation tools for a `Subreddit`, including managing users (e.g., banning, muting), flair, and content policies at the community level. + +**Related Classes/Methods**: + +* `SubredditModeration:82-199 `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/.codeboarding/analysis.json b/.codeboarding/analysis.json new file mode 100644 index 000000000..100cb1fae --- /dev/null +++ b/.codeboarding/analysis.json @@ -0,0 +1,176 @@ +{ + "description": "PRAW (Python Reddit API Wrapper) is structured around a clear separation of concerns, facilitating robust and flexible interaction with the Reddit API. At its core, the API Client Core (`praw.reddit.Reddit`) serves as the central communication hub, managing all HTTP requests, authentication, and rate limiting. It relies on the Configuration Manager (`praw.config.Config`) to load and provide necessary settings, ensuring proper API access.\n\nUpon receiving raw JSON responses from the Reddit API, the API Client Core forwards this data to the Object Hydrator (`praw.objector.Objector`). The Object Hydrator is responsible for transforming these generic JSON structures into rich, interactive Python objects, which are instances of the Reddit Data Models (e.g., `praw.models.reddit.submission.Submission`, `praw.models.reddit.comment.Comment`, `praw.models.reddit.redditor.Redditor`, `praw.models.reddit.subreddit.Subreddit`). These models encapsulate Reddit entities and provide methods for further interaction.\n\nTo simplify complex API operations, API Interaction Facades provide high-level, domain-specific interfaces. These facades, such as `praw.models.listing.generator.ListingGenerator` for listing content, `praw.models.util.stream_generator` for streaming, and various methods within `praw.models.reddit.subreddit.Subreddit`, `praw.models.reddit.modmail`, `praw.models.mod_notes`, `praw.models.reddit.redditor.Redditor`, and `praw.models.auth.Auth`, abstract the underlying API calls. They send requests through the API Client Core and operate on the Reddit Data Models, allowing developers to interact with Reddit entities in an intuitive, object-oriented manner. The Reddit Data Models themselves can also initiate requests back through the API Client Core for entity-specific actions.", + "components": [ + { + "name": "API Client Core", + "description": "The central component for all Reddit API communication, handling HTTP requests, authentication, and rate limiting. It acts as the primary interface for other components to communicate with Reddit.", + "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 + } + ], + "can_expand": true + }, + { + "name": "Configuration Manager", + "description": "Responsible for loading, parsing, and providing PRAW's configuration settings from various sources (e.g., `praw.ini`, environment variables).", + "referenced_source_code": [ + { + "qualified_name": "praw.config.Config", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/config.py", + "reference_start_line": 52, + "reference_end_line": 52 + } + ], + "can_expand": true + }, + { + "name": "Object Hydrator", + "description": "Transforms raw JSON data received from the Reddit API into rich, interactive Python objects (PRAW models), converting generic API responses into type-safe and method-rich objects.", + "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 + } + ], + "can_expand": true + }, + { + "name": "Reddit Data Models", + "description": "A comprehensive collection of classes representing various Reddit entities (e.g., `Submission`, `Comment`, `Redditor`, `Subreddit`). These objects encapsulate data and provide entity-specific methods for interaction.", + "referenced_source_code": [ + { + "qualified_name": "praw.models.reddit.submission.Submission", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/submission.py", + "reference_start_line": 716, + "reference_end_line": 716 + }, + { + "qualified_name": "praw.models.reddit.comment.Comment", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/comment.py", + "reference_start_line": 328, + "reference_end_line": 328 + }, + { + "qualified_name": "praw.models.reddit.redditor.Redditor", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/redditor.py", + "reference_start_line": 421, + "reference_end_line": 421 + }, + { + "qualified_name": "praw.models.reddit.subreddit.Subreddit", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/subreddit.py", + "reference_start_line": 2446, + "reference_end_line": 2446 + } + ], + "can_expand": true + }, + { + "name": "API Interaction Facades", + "description": "Provides high-level, domain-specific interfaces for interacting with the Reddit API, abstracting complex operations and data retrieval patterns. This component groups functionalities like listing/streaming, subreddit management, moderation tools, and user/authentication specific actions.", + "referenced_source_code": [ + { + "qualified_name": "praw.models.listing.generator.ListingGenerator", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py", + "reference_start_line": 17, + "reference_end_line": 103 + }, + { + "qualified_name": "praw.models.util.stream_generator", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/util.py", + "reference_start_line": 36, + "reference_end_line": 163 + }, + { + "qualified_name": "praw.models.reddit.subreddit.Subreddit", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/subreddit.py", + "reference_start_line": 2446, + "reference_end_line": 2446 + }, + { + "qualified_name": "praw.models.reddit.modmail", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/modmail.py", + "reference_start_line": 0, + "reference_end_line": 0 + }, + { + "qualified_name": "praw.models.mod_notes", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/mod_notes.py", + "reference_start_line": 0, + "reference_end_line": 0 + }, + { + "qualified_name": "praw.models.reddit.redditor.Redditor", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/redditor.py", + "reference_start_line": 421, + "reference_end_line": 421 + }, + { + "qualified_name": "praw.models.auth.Auth", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/auth.py", + "reference_start_line": 11, + "reference_end_line": 125 + } + ], + "can_expand": true + } + ], + "components_relations": [ + { + "relation": "provides settings to", + "src_name": "Configuration Manager", + "dst_name": "API Client Core" + }, + { + "relation": "reads configuration from", + "src_name": "API Client Core", + "dst_name": "Configuration Manager" + }, + { + "relation": "sends requests via", + "src_name": "API Interaction Facades", + "dst_name": "API Client Core" + }, + { + "relation": "executes actions for", + "src_name": "API Client Core", + "dst_name": "API Interaction Facades" + }, + { + "relation": "sends raw API response to", + "src_name": "API Client Core", + "dst_name": "Object Hydrator" + }, + { + "relation": "returns PRAW objects to", + "src_name": "Object Hydrator", + "dst_name": "API Client Core" + }, + { + "relation": "creates and populates", + "src_name": "API Client Core", + "dst_name": "Reddit Data Models" + }, + { + "relation": "operates on", + "src_name": "API Interaction Facades", + "dst_name": "Reddit Data Models" + }, + { + "relation": "are managed by", + "src_name": "Reddit Data Models", + "dst_name": "API Interaction Facades" + }, + { + "relation": "initiate requests via", + "src_name": "Reddit Data Models", + "dst_name": "API Client Core" + } + ] +} diff --git a/.codeboarding/codeboarding_version.json b/.codeboarding/codeboarding_version.json new file mode 100644 index 000000000..89e257292 --- /dev/null +++ b/.codeboarding/codeboarding_version.json @@ -0,0 +1,4 @@ +{ + "commit_hash": "3a1249a579ce1b58816a4e74ae7ffa22e28042ae", + "code_boarding_version": "0.1.0" +} diff --git a/.codeboarding/overview.rst b/.codeboarding/overview.rst new file mode 100644 index 000000000..71d037ebb --- /dev/null +++ b/.codeboarding/overview.rst @@ -0,0 +1,114 @@ +Overview +======== + +.. mermaid:: + + graph LR + API_Client_Core["API Client Core"] + Configuration_Manager["Configuration Manager"] + Object_Hydrator["Object Hydrator"] + Reddit_Data_Models["Reddit Data Models"] + API_Interaction_Facades["API Interaction Facades"] + Configuration_Manager -- "provides settings to" --> API_Client_Core + API_Client_Core -- "reads configuration from" --> Configuration_Manager + API_Interaction_Facades -- "sends requests via" --> API_Client_Core + API_Client_Core -- "executes actions for" --> API_Interaction_Facades + API_Client_Core -- "sends raw API response to" --> Object_Hydrator + Object_Hydrator -- "returns PRAW objects to" --> API_Client_Core + API_Client_Core -- "creates and populates" --> Reddit_Data_Models + API_Interaction_Facades -- "operates on" --> Reddit_Data_Models + Reddit_Data_Models -- "are managed by" --> API_Interaction_Facades + Reddit_Data_Models -- "initiate requests via" --> API_Client_Core + click API_Client_Core href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/API_Client_Core.html" "Details" + click Configuration_Manager href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Configuration_Manager.html" "Details" + click Object_Hydrator href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Object_Hydrator.html" "Details" + click Reddit_Data_Models href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Reddit_Data_Models.html" "Details" + click API_Interaction_Facades href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/API_Interaction_Facades.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 +------- + +PRAW (Python Reddit API Wrapper) is structured around a clear separation of concerns, facilitating robust and flexible interaction with the Reddit API. At its core, the API Client Core (`praw.reddit.Reddit`) serves as the central communication hub, managing all HTTP requests, authentication, and rate limiting. It relies on the Configuration Manager (`praw.config.Config`) to load and provide necessary settings, ensuring proper API access. + +Upon receiving raw JSON responses from the Reddit API, the API Client Core forwards this data to the Object Hydrator (`praw.objector.Objector`). The Object Hydrator is responsible for transforming these generic JSON structures into rich, interactive Python objects, which are instances of the Reddit Data Models (e.g., `praw.models.reddit.submission.Submission`, `praw.models.reddit.comment.Comment`, `praw.models.reddit.redditor.Redditor`, `praw.models.reddit.subreddit.Subreddit`). These models encapsulate Reddit entities and provide methods for further interaction. + +To simplify complex API operations, API Interaction Facades provide high-level, domain-specific interfaces. These facades, such as `praw.models.listing.generator.ListingGenerator` for listing content, `praw.models.util.stream_generator` for streaming, and various methods within `praw.models.reddit.subreddit.Subreddit`, `praw.models.reddit.modmail`, `praw.models.mod_notes`, `praw.models.reddit.redditor.Redditor`, and `praw.models.auth.Auth`, abstract the underlying API calls. They send requests through the API Client Core and operate on the Reddit Data Models, allowing developers to interact with Reddit entities in an intuitive, object-oriented manner. The Reddit Data Models themselves can also initiate requests back through the API Client Core for entity-specific actions. + +API Client Core +^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +The central component for all Reddit API communication, handling HTTP requests, authentication, and rate limiting. It acts as the primary interface for other components to communicate with Reddit. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit:57-901 `_ + +Configuration Manager +^^^^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +Responsible for loading, parsing, and providing PRAW's configuration settings from various sources (e.g., `praw.ini`, environment variables). + +**Related Classes/Methods**: + +* `praw.config.Config `_ + +Object Hydrator +^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +Transforms raw JSON data received from the Reddit API into rich, interactive Python objects (PRAW models), converting generic API responses into type-safe and method-rich objects. + +**Related Classes/Methods**: + +* `praw.objector.Objector:17-263 `_ + +Reddit Data Models +^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +A comprehensive collection of classes representing various Reddit entities (e.g., `Submission`, `Comment`, `Redditor`, `Subreddit`). These objects encapsulate data and provide entity-specific methods for interaction. + +**Related Classes/Methods**: + +* `praw.models.reddit.submission.Submission `_ +* `praw.models.reddit.comment.Comment `_ +* `praw.models.reddit.redditor.Redditor `_ +* `praw.models.reddit.subreddit.Subreddit `_ + +API Interaction Facades +^^^^^^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +Provides high-level, domain-specific interfaces for interacting with the Reddit API, abstracting complex operations and data retrieval patterns. This component groups functionalities like listing/streaming, subreddit management, moderation tools, and user/authentication specific actions. + +**Related Classes/Methods**: + +* `praw.models.listing.generator.ListingGenerator:17-103 `_ +* `praw.models.util.stream_generator:36-163 `_ +* `praw.models.reddit.subreddit.Subreddit `_ +* `praw.models.reddit.modmail `_ +* `praw.models.mod_notes `_ +* `praw.models.reddit.redditor.Redditor `_ +* `praw.models.auth.Auth:11-125 `_ + + +FAQ +--- + +`See the FAQ `_ From 6b3fa897303d414ede32c3788db04b0fcd124e37 Mon Sep 17 00:00:00 2001 From: ivanmilevtues Date: Mon, 1 Sep 2025 21:08:03 +0200 Subject: [PATCH 12/23] Small fix --- .codeboarding/API_Client_Core.json | 196 --------------------- .codeboarding/API_Client_Core.rst | 123 ------------- .codeboarding/API_Interaction_Facades.json | 158 ----------------- .codeboarding/API_Interaction_Facades.rst | 108 ------------ .codeboarding/Configuration_Manager.json | 174 ------------------ .codeboarding/Configuration_Manager.rst | 90 ---------- .codeboarding/Object_Hydrator.json | 68 ------- .codeboarding/Object_Hydrator.rst | 60 ------- .codeboarding/Reddit_Data_Models.json | 166 ----------------- .codeboarding/Reddit_Data_Models.rst | 117 ------------ .codeboarding/analysis.json | 176 ------------------ .codeboarding/codeboarding_version.json | 4 - .codeboarding/overview.rst | 114 ------------ .github/workflows/docs_codeboarding.yml | 26 +-- 14 files changed, 13 insertions(+), 1567 deletions(-) delete mode 100644 .codeboarding/API_Client_Core.json delete mode 100644 .codeboarding/API_Client_Core.rst delete mode 100644 .codeboarding/API_Interaction_Facades.json delete mode 100644 .codeboarding/API_Interaction_Facades.rst delete mode 100644 .codeboarding/Configuration_Manager.json delete mode 100644 .codeboarding/Configuration_Manager.rst delete mode 100644 .codeboarding/Object_Hydrator.json delete mode 100644 .codeboarding/Object_Hydrator.rst delete mode 100644 .codeboarding/Reddit_Data_Models.json delete mode 100644 .codeboarding/Reddit_Data_Models.rst delete mode 100644 .codeboarding/analysis.json delete mode 100644 .codeboarding/codeboarding_version.json delete mode 100644 .codeboarding/overview.rst diff --git a/.codeboarding/API_Client_Core.json b/.codeboarding/API_Client_Core.json deleted file mode 100644 index 3e37e378f..000000000 --- a/.codeboarding/API_Client_Core.json +++ /dev/null @@ -1,196 +0,0 @@ -{ - "description": "The PRAW client subsystem provides a high-level, Pythonic interface for interacting with the Reddit API. At its core, the Reddit Client acts as a facade, orchestrating API requests and managing the overall session. It leverages Prawcore Integration for secure, low-level HTTP communication and authentication. All API interactions are routed through the Request Handler, which executes requests, processes raw responses, and applies Rate Limiting Mechanism to ensure API compliance. The raw API data is then transformed into rich Python objects by the Object Preparation component. Users interact with specific Reddit resources through Resource Accessors, which in turn utilize the Object Generator for handling collections and paginated results. The Asynchronous Operations Manager ensures proper behavior within asynchronous environments, influencing how requests are handled and resources are accessed. This architecture ensures a robust, user-friendly, and compliant interaction with the Reddit platform.", - "components": [ - { - "name": "Reddit Client", - "description": "Acts as the primary entry point and facade for all Reddit API interactions, orchestrating the setup and coordination of other components, and managing the overall API session.", - "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 - } - ], - "can_expand": true - }, - { - "name": "Prawcore Integration", - "description": "Manages the low-level HTTP communication and authentication with the Reddit API, handling token acquisition, refreshing, and secure credential management. This component's direct source code from `prawcore` could not be retrieved. Its role is inferred from its initialization and usage within the `Reddit` client.", - "referenced_source_code": [ - { - "qualified_name": "praw.reddit.Reddit._prepare_prawcore", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", - "reference_start_line": 700, - "reference_end_line": 730 - } - ], - "can_expand": true - }, - { - "name": "Request Handler", - "description": "Executes the actual HTTP requests to the Reddit API and processes the raw responses, transforming raw API data into structured Python objects.", - "referenced_source_code": [ - { - "qualified_name": "praw.reddit.Reddit.request", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", - "reference_start_line": 860, - "reference_end_line": 901 - } - ], - "can_expand": true - }, - { - "name": "Rate Limiting Mechanism", - "description": "Enforces Reddit API rate limits to ensure compliance and prevent the client from being temporarily blocked.", - "referenced_source_code": [ - { - "qualified_name": "praw.reddit.Reddit._handle_rate_limit", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", - "reference_start_line": 649, - "reference_end_line": 666 - } - ], - "can_expand": false - }, - { - "name": "Object Preparation", - "description": "Configures the mechanism for converting raw JSON responses from the Reddit API into rich, type-safe PRAW Python objects.", - "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 - } - ], - "can_expand": true - }, - { - "name": "Resource Accessors", - "description": "Provides a Pythonic interface for interacting with specific Reddit API endpoints and resources (e.g., fetching comments, submitting posts).", - "referenced_source_code": [ - { - "qualified_name": "praw.reddit.Reddit.get", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", - "reference_start_line": 790, - "reference_end_line": 797 - } - ], - "can_expand": true - }, - { - "name": "Object Generator", - "description": "Facilitates the retrieval and iteration of collections of Reddit objects (e.g., lists of submissions or comments), often used for paginated results.", - "referenced_source_code": [ - { - "qualified_name": "praw.models.listing.generator.ListingGenerator", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py", - "reference_start_line": 17, - "reference_end_line": 103 - } - ], - "can_expand": true - }, - { - "name": "Asynchronous Operations Manager", - "description": "Determines and manages the asynchronous nature of API requests, integrating with Python's `asyncio`.", - "referenced_source_code": [ - { - "qualified_name": "praw.reddit.Reddit._check_for_async", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", - "reference_start_line": 609, - "reference_end_line": 630 - } - ], - "can_expand": true - } - ], - "components_relations": [ - { - "relation": "Initializes and configures", - "src_name": "Reddit Client", - "dst_name": "Prawcore Integration" - }, - { - "relation": "Delegates API calls to", - "src_name": "Reddit Client", - "dst_name": "Request Handler" - }, - { - "relation": "Initializes", - "src_name": "Reddit Client", - "dst_name": "Object Preparation" - }, - { - "relation": "Provides services to", - "src_name": "Prawcore Integration", - "dst_name": "Request Handler" - }, - { - "relation": "Queries", - "src_name": "Request Handler", - "dst_name": "Asynchronous Operations Manager" - }, - { - "relation": "Uses", - "src_name": "Request Handler", - "dst_name": "Object Preparation" - }, - { - "relation": "Relies on", - "src_name": "Request Handler", - "dst_name": "Prawcore Integration" - }, - { - "relation": "Is influenced by", - "src_name": "Request Handler", - "dst_name": "Rate Limiting Mechanism" - }, - { - "relation": "Enforces restrictions on", - "src_name": "Rate Limiting Mechanism", - "dst_name": "Request Handler" - }, - { - "relation": "Is consulted by", - "src_name": "Rate Limiting Mechanism", - "dst_name": "Resource Accessors" - }, - { - "relation": "Converts data for", - "src_name": "Object Preparation", - "dst_name": "Request Handler" - }, - { - "relation": "Sends API requests to", - "src_name": "Resource Accessors", - "dst_name": "Request Handler" - }, - { - "relation": "Leverages", - "src_name": "Resource Accessors", - "dst_name": "Object Generator" - }, - { - "relation": "Is influenced by", - "src_name": "Resource Accessors", - "dst_name": "Asynchronous Operations Manager" - }, - { - "relation": "Provides sequences of objects to", - "src_name": "Object Generator", - "dst_name": "Resource Accessors" - }, - { - "relation": "Informs", - "src_name": "Asynchronous Operations Manager", - "dst_name": "Request Handler" - }, - { - "relation": "Influences", - "src_name": "Asynchronous Operations Manager", - "dst_name": "Resource Accessors" - } - ] -} diff --git a/.codeboarding/API_Client_Core.rst b/.codeboarding/API_Client_Core.rst deleted file mode 100644 index 403dce5e0..000000000 --- a/.codeboarding/API_Client_Core.rst +++ /dev/null @@ -1,123 +0,0 @@ -Api Client Core -=============== - -.. mermaid:: - - graph LR - Reddit_Client["Reddit Client"] - Prawcore_Integration["Prawcore Integration"] - Request_Handler["Request Handler"] - Rate_Limiting_Mechanism["Rate Limiting Mechanism"] - Object_Preparation["Object Preparation"] - Resource_Accessors["Resource Accessors"] - Object_Generator["Object Generator"] - Asynchronous_Operations_Manager["Asynchronous Operations Manager"] - Reddit_Client -- "Initializes and configures" --> Prawcore_Integration - Reddit_Client -- "Delegates API calls to" --> Request_Handler - Reddit_Client -- "Initializes" --> Object_Preparation - Prawcore_Integration -- "Provides services to" --> Request_Handler - Request_Handler -- "Queries" --> Asynchronous_Operations_Manager - Request_Handler -- "Uses" --> Object_Preparation - Request_Handler -- "Relies on" --> Prawcore_Integration - Request_Handler -- "Is influenced by" --> Rate_Limiting_Mechanism - Rate_Limiting_Mechanism -- "Enforces restrictions on" --> Request_Handler - Rate_Limiting_Mechanism -- "Is consulted by" --> Resource_Accessors - Object_Preparation -- "Converts data for" --> Request_Handler - Resource_Accessors -- "Sends API requests to" --> Request_Handler - Resource_Accessors -- "Leverages" --> Object_Generator - Resource_Accessors -- "Is influenced by" --> Asynchronous_Operations_Manager - Object_Generator -- "Provides sequences of objects to" --> Resource_Accessors - Asynchronous_Operations_Manager -- "Informs" --> Request_Handler - Asynchronous_Operations_Manager -- "Influences" --> Resource_Accessors - -| |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 client subsystem provides a high-level, Pythonic interface for interacting with the Reddit API. At its core, the Reddit Client acts as a facade, orchestrating API requests and managing the overall session. It leverages Prawcore Integration for secure, low-level HTTP communication and authentication. All API interactions are routed through the Request Handler, which executes requests, processes raw responses, and applies Rate Limiting Mechanism to ensure API compliance. The raw API data is then transformed into rich Python objects by the Object Preparation component. Users interact with specific Reddit resources through Resource Accessors, which in turn utilize the Object Generator for handling collections and paginated results. The Asynchronous Operations Manager ensures proper behavior within asynchronous environments, influencing how requests are handled and resources are accessed. This architecture ensures a robust, user-friendly, and compliant interaction with the Reddit platform. - -Reddit Client -^^^^^^^^^^^^^ - -Acts as the primary entry point and facade for all Reddit API interactions, orchestrating the setup and coordination of other components, and managing the overall API session. - -**Related Classes/Methods**: - -* `praw.reddit.Reddit:57-901 `_ - -Prawcore Integration -^^^^^^^^^^^^^^^^^^^^ - -Manages the low-level HTTP communication and authentication with the Reddit API, handling token acquisition, refreshing, and secure credential management. This component's direct source code from `prawcore` could not be retrieved. Its role is inferred from its initialization and usage within the `Reddit` client. - -**Related Classes/Methods**: - -* `praw.reddit.Reddit._prepare_prawcore:700-730 `_ - -Request Handler -^^^^^^^^^^^^^^^ - -Executes the actual HTTP requests to the Reddit API and processes the raw responses, transforming raw API data into structured Python objects. - -**Related Classes/Methods**: - -* `praw.reddit.Reddit.request:860-901 `_ - -Rate Limiting Mechanism -^^^^^^^^^^^^^^^^^^^^^^^ - -Enforces Reddit API rate limits to ensure compliance and prevent the client from being temporarily blocked. - -**Related Classes/Methods**: - -* `praw.reddit.Reddit._handle_rate_limit:649-666 `_ - -Object Preparation -^^^^^^^^^^^^^^^^^^ - -Configures the mechanism for converting raw JSON responses from the Reddit API into rich, type-safe PRAW Python objects. - -**Related Classes/Methods**: - -* `praw.objector.Objector:17-263 `_ - -Resource Accessors -^^^^^^^^^^^^^^^^^^ - -Provides a Pythonic interface for interacting with specific Reddit API endpoints and resources (e.g., fetching comments, submitting posts). - -**Related Classes/Methods**: - -* `praw.reddit.Reddit.get:790-797 `_ - -Object Generator -^^^^^^^^^^^^^^^^ - -Facilitates the retrieval and iteration of collections of Reddit objects (e.g., lists of submissions or comments), often used for paginated results. - -**Related Classes/Methods**: - -* `praw.models.listing.generator.ListingGenerator:17-103 `_ - -Asynchronous Operations Manager -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Determines and manages the asynchronous nature of API requests, integrating with Python's `asyncio`. - -**Related Classes/Methods**: - -* `praw.reddit.Reddit._check_for_async:609-630 `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/.codeboarding/API_Interaction_Facades.json b/.codeboarding/API_Interaction_Facades.json deleted file mode 100644 index 7333d2c7b..000000000 --- a/.codeboarding/API_Interaction_Facades.json +++ /dev/null @@ -1,158 +0,0 @@ -{ - "description": "The `API Interaction Facades` subsystem encompasses high-level, domain-specific interfaces for interacting with the Reddit API. It abstracts complex operations and data retrieval patterns, grouping functionalities related to listing/streaming, subreddit management, moderation tools, and user/authentication specific actions.", - "components": [ - { - "name": "Subreddit", - "description": "Primary facade for all subreddit-related operations, including content submission, moderation, flair management, appearance customization, and data retrieval. It provides a high-level interface for interacting with a specific subreddit.", - "referenced_source_code": [ - { - "qualified_name": "praw.models.reddit.subreddit.Subreddit", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/subreddit.py", - "reference_start_line": 2446, - "reference_end_line": 2446 - } - ], - "can_expand": true - }, - { - "name": "Redditor", - "description": "Represents a Reddit user and provides methods for user-specific actions such as profile interaction, friendship management, and accessing user-generated content (submissions, comments).", - "referenced_source_code": [ - { - "qualified_name": "praw.models.reddit.redditor.Redditor", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/redditor.py", - "reference_start_line": 421, - "reference_end_line": 421 - } - ], - "can_expand": true - }, - { - "name": "Modmail", - "description": "Manages modmail conversations within a specific subreddit, enabling functionalities like reading, replying to, and managing modmail threads.", - "referenced_source_code": [ - { - "qualified_name": "praw.models.reddit.modmail.Modmail", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/modmail.py", - "reference_start_line": 1, - "reference_end_line": 1 - } - ], - "can_expand": false - }, - { - "name": "ModNotes", - "description": "Facilitates the creation, retrieval, and deletion of moderator notes associated with various Reddit entities (e.g., users, submissions).", - "referenced_source_code": [ - { - "qualified_name": "praw.models.mod_notes.ModNotes", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/mod_notes.py", - "reference_start_line": 1, - "reference_end_line": 1 - } - ], - "can_expand": true - }, - { - "name": "Auth", - "description": "Manages the authentication and authorization processes with the Reddit API, ensuring all outgoing requests are properly credentialed and secure.", - "referenced_source_code": [ - { - "qualified_name": "praw.models.auth.Auth", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/auth.py", - "reference_start_line": 11, - "reference_end_line": 125 - } - ], - "can_expand": true - }, - { - "name": "ListingGenerator", - "description": "Provides an iterable interface for fetching paginated data from various Reddit API endpoints, handling the underlying pagination logic transparently.", - "referenced_source_code": [ - { - "qualified_name": "praw.models.listing.generator.ListingGenerator", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py", - "reference_start_line": 17, - "reference_end_line": 103 - } - ], - "can_expand": true - }, - { - "name": "stream_generator", - "description": "Offers a resilient and generic streaming mechanism for continuous data retrieval from Reddit, incorporating features like rate limiting, duplicate detection, and exponential backoff for robust operation.", - "referenced_source_code": [ - { - "qualified_name": "praw.models.util.stream_generator", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/util.py", - "reference_start_line": 36, - "reference_end_line": 163 - } - ], - "can_expand": true - } - ], - "components_relations": [ - { - "relation": "delegates to", - "src_name": "Subreddit", - "dst_name": "Modmail" - }, - { - "relation": "interacts with", - "src_name": "Subreddit", - "dst_name": "ModNotes" - }, - { - "relation": "utilizes", - "src_name": "Subreddit", - "dst_name": "ListingGenerator" - }, - { - "relation": "leverages", - "src_name": "Subreddit", - "dst_name": "stream_generator" - }, - { - "relation": "relies on", - "src_name": "Subreddit", - "dst_name": "Auth" - }, - { - "relation": "utilizes", - "src_name": "Redditor", - "dst_name": "ListingGenerator" - }, - { - "relation": "leverages", - "src_name": "Redditor", - "dst_name": "stream_generator" - }, - { - "relation": "relies on", - "src_name": "Redditor", - "dst_name": "Auth" - }, - { - "relation": "relies on", - "src_name": "Modmail", - "dst_name": "Auth" - }, - { - "relation": "relies on", - "src_name": "ModNotes", - "dst_name": "Auth" - }, - { - "relation": "relies on", - "src_name": "ListingGenerator", - "dst_name": "Auth" - }, - { - "relation": "relies on", - "src_name": "stream_generator", - "dst_name": "Auth" - } - ] -} diff --git a/.codeboarding/API_Interaction_Facades.rst b/.codeboarding/API_Interaction_Facades.rst deleted file mode 100644 index f3214d09f..000000000 --- a/.codeboarding/API_Interaction_Facades.rst +++ /dev/null @@ -1,108 +0,0 @@ -Api Interaction Facades -======================= - -.. mermaid:: - - graph LR - Subreddit["Subreddit"] - Redditor["Redditor"] - Modmail["Modmail"] - ModNotes["ModNotes"] - Auth["Auth"] - ListingGenerator["ListingGenerator"] - stream_generator["stream_generator"] - Subreddit -- "delegates to" --> Modmail - Subreddit -- "interacts with" --> ModNotes - Subreddit -- "utilizes" --> ListingGenerator - Subreddit -- "leverages" --> stream_generator - Subreddit -- "relies on" --> Auth - Redditor -- "utilizes" --> ListingGenerator - Redditor -- "leverages" --> stream_generator - Redditor -- "relies on" --> Auth - Modmail -- "relies on" --> Auth - ModNotes -- "relies on" --> Auth - ListingGenerator -- "relies on" --> Auth - stream_generator -- "relies on" --> Auth - -| |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 `API Interaction Facades` subsystem encompasses high-level, domain-specific interfaces for interacting with the Reddit API. It abstracts complex operations and data retrieval patterns, grouping functionalities related to listing/streaming, subreddit management, moderation tools, and user/authentication specific actions. - -Subreddit -^^^^^^^^^ - -Primary facade for all subreddit-related operations, including content submission, moderation, flair management, appearance customization, and data retrieval. It provides a high-level interface for interacting with a specific subreddit. - -**Related Classes/Methods**: - -* `praw.models.reddit.subreddit.Subreddit `_ - -Redditor -^^^^^^^^ - -Represents a Reddit user and provides methods for user-specific actions such as profile interaction, friendship management, and accessing user-generated content (submissions, comments). - -**Related Classes/Methods**: - -* `praw.models.reddit.redditor.Redditor `_ - -Modmail -^^^^^^^ - -Manages modmail conversations within a specific subreddit, enabling functionalities like reading, replying to, and managing modmail threads. - -**Related Classes/Methods**: - -* `praw.models.reddit.modmail.Modmail `_ - -ModNotes -^^^^^^^^ - -Facilitates the creation, retrieval, and deletion of moderator notes associated with various Reddit entities (e.g., users, submissions). - -**Related Classes/Methods**: - -* `praw.models.mod_notes.ModNotes `_ - -Auth -^^^^ - -Manages the authentication and authorization processes with the Reddit API, ensuring all outgoing requests are properly credentialed and secure. - -**Related Classes/Methods**: - -* `praw.models.auth.Auth:11-125 `_ - -ListingGenerator -^^^^^^^^^^^^^^^^ - -Provides an iterable interface for fetching paginated data from various Reddit API endpoints, handling the underlying pagination logic transparently. - -**Related Classes/Methods**: - -* `praw.models.listing.generator.ListingGenerator:17-103 `_ - -stream_generator -^^^^^^^^^^^^^^^^ - -Offers a resilient and generic streaming mechanism for continuous data retrieval from Reddit, incorporating features like rate limiting, duplicate detection, and exponential backoff for robust operation. - -**Related Classes/Methods**: - -* `praw.models.util.stream_generator:36-163 `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/.codeboarding/Configuration_Manager.json b/.codeboarding/Configuration_Manager.json deleted file mode 100644 index f0943c1e1..000000000 --- a/.codeboarding/Configuration_Manager.json +++ /dev/null @@ -1,174 +0,0 @@ -{ - "description": "The PRAW library's core subsystem is designed around a clear separation of concerns, enabling robust and flexible interaction with the Reddit API. At its heart, the `Reddit` class acts as the central orchestrator, coordinating various specialized components for configuration, API communication, authentication, and response processing. This architecture ensures that PRAW can adapt to different environments and authentication schemes while providing a consistent and intuitive interface for developers.", - "components": [ - { - "name": "Reddit API Interface", - "description": "The primary entry point for developers to interact with the Reddit API. It initializes and manages the lifecycle of other core components, providing high-level methods for accessing 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 - } - ], - "can_expand": true - }, - { - "name": "Configuration Manager", - "description": "This component centralizes and manages all configuration settings required by the PRAW library. It handles reading configurations from external files (like `praw.ini`) and environment variables, applying default values, and making these settings available throughout the application.", - "referenced_source_code": [ - { - "qualified_name": "praw.config.Config", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/config.py", - "reference_start_line": 52, - "reference_end_line": 52 - }, - { - "qualified_name": "praw.ini", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/praw.ini", - "reference_start_line": 1, - "reference_end_line": 1 - }, - { - "qualified_name": "os.getenv", - "reference_file": null, - "reference_start_line": 1, - "reference_end_line": 1 - } - ], - "can_expand": false - }, - { - "name": "API Client/Connector (Prawcore Requestor)", - "description": "Responsible for executing the actual HTTP requests to the Reddit API. It utilizes the base URL and user agent provided by the configuration and handles the low-level network communication. This component is part of the `prawcore` library, a core dependency of PRAW.", - "referenced_source_code": [ - { - "qualified_name": "prawcore.requestor.Requestor", - "reference_file": null, - "reference_start_line": 1, - "reference_end_line": 1 - } - ], - "can_expand": true - }, - { - "name": "Authentication Module", - "description": "Manages the various authentication flows required to interact with the Reddit API. It uses credentials (client ID, client secret, redirect URI) from the configuration to establish and maintain authenticated sessions.", - "referenced_source_code": [ - { - "qualified_name": "praw.models.Auth", - "reference_file": null, - "reference_start_line": 1, - "reference_end_line": 1 - }, - { - "qualified_name": "prawcore.auth.TrustedAuthenticator", - "reference_file": null, - "reference_start_line": 1, - "reference_end_line": 1 - }, - { - "qualified_name": "prawcore.auth.UntrustedAuthenticator", - "reference_file": null, - "reference_start_line": 1, - "reference_end_line": 1 - }, - { - "qualified_name": "prawcore.auth.ReadOnlyAuthorizer", - "reference_file": null, - "reference_start_line": 1, - "reference_end_line": 1 - }, - { - "qualified_name": "prawcore.auth.ScriptAuthorizer", - "reference_file": null, - "reference_start_line": 1, - "reference_end_line": 1 - }, - { - "qualified_name": "prawcore.auth.DeviceIDAuthorizer", - "reference_file": null, - "reference_start_line": 1, - "reference_end_line": 1 - } - ], - "can_expand": true - }, - { - "name": "Response Objector", - "description": "Processes raw JSON responses received from the Reddit API, transforming them into structured PRAW-specific Python objects (e.g., `Comment`, `Submission`, `Redditor`). It also handles the parsing of API-specific errors.", - "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 - } - ], - "can_expand": true - } - ], - "components_relations": [ - { - "relation": "Initializes and uses", - "src_name": "Reddit API Interface", - "dst_name": "Configuration Manager" - }, - { - "relation": "Initializes and uses", - "src_name": "Reddit API Interface", - "dst_name": "API Client/Connector (Prawcore Requestor)" - }, - { - "relation": "Initializes and uses", - "src_name": "Reddit API Interface", - "dst_name": "Authentication Module" - }, - { - "relation": "Initializes and uses", - "src_name": "Reddit API Interface", - "dst_name": "Response Objector" - }, - { - "relation": "Provides configuration to", - "src_name": "Configuration Manager", - "dst_name": "Reddit API Interface" - }, - { - "relation": "sends requests to", - "src_name": "Reddit API Interface", - "dst_name": "API Client/Connector (Prawcore Requestor)" - }, - { - "relation": "Provides authentication parameters to", - "src_name": "Configuration Manager", - "dst_name": "Authentication Module" - }, - { - "relation": "authenticates requests for", - "src_name": "Authentication Module", - "dst_name": "API Client/Connector (Prawcore Requestor)" - }, - { - "relation": "returns raw data to", - "src_name": "API Client/Connector (Prawcore Requestor)", - "dst_name": "Response Objector" - }, - { - "relation": "Returns PRAW objects to", - "src_name": "Response Objector", - "dst_name": "Reddit API Interface" - }, - { - "relation": "configures", - "src_name": "Reddit API Interface", - "dst_name": "Authentication Module" - }, - { - "relation": "configures", - "src_name": "Reddit API Interface", - "dst_name": "API Client/Connector (Prawcore Requestor)" - } - ] -} diff --git a/.codeboarding/Configuration_Manager.rst b/.codeboarding/Configuration_Manager.rst deleted file mode 100644 index cfa734acf..000000000 --- a/.codeboarding/Configuration_Manager.rst +++ /dev/null @@ -1,90 +0,0 @@ -Configuration Manager -===================== - -.. mermaid:: - - graph LR - Reddit_API_Interface["Reddit API Interface"] - Configuration_Manager["Configuration Manager"] - API_Client_Connector_Prawcore_Requestor_["API Client/Connector (Prawcore Requestor)"] - Authentication_Module["Authentication Module"] - Response_Objector["Response Objector"] - Reddit_API_Interface -- "Initializes and uses" --> Configuration_Manager - Reddit_API_Interface -- "Initializes and uses" --> API_Client_Connector_Prawcore_Requestor_ - Reddit_API_Interface -- "Initializes and uses" --> Authentication_Module - Reddit_API_Interface -- "Initializes and uses" --> Response_Objector - Configuration_Manager -- "Provides configuration to" --> Reddit_API_Interface - Reddit_API_Interface -- "sends requests to" --> API_Client_Connector_Prawcore_Requestor_ - Configuration_Manager -- "Provides authentication parameters to" --> Authentication_Module - Authentication_Module -- "authenticates requests for" --> API_Client_Connector_Prawcore_Requestor_ - API_Client_Connector_Prawcore_Requestor_ -- "returns raw data to" --> Response_Objector - Response_Objector -- "Returns PRAW objects to" --> Reddit_API_Interface - Reddit_API_Interface -- "configures" --> Authentication_Module - Reddit_API_Interface -- "configures" --> API_Client_Connector_Prawcore_Requestor_ - 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 subsystem is designed around a clear separation of concerns, enabling robust and flexible interaction with the Reddit API. At its heart, the `Reddit` class acts as the central orchestrator, coordinating various specialized components for configuration, API communication, authentication, and response processing. This architecture ensures that PRAW can adapt to different environments and authentication schemes while providing a consistent and intuitive interface for developers. - -Reddit API Interface -^^^^^^^^^^^^^^^^^^^^ - -The primary entry point for developers to interact with the Reddit API. It initializes and manages the lifecycle of other core components, providing high-level methods for accessing Reddit resources. - -**Related Classes/Methods**: - -* `praw.reddit.Reddit:57-901 `_ - -Configuration Manager -^^^^^^^^^^^^^^^^^^^^^ - -:ref:`Expand ` - -This component centralizes and manages all configuration settings required by the PRAW library. It handles reading configurations from external files (like `praw.ini`) and environment variables, applying default values, and making these settings available throughout the application. - -**Related Classes/Methods**: - -* `praw.config.Config `_ -* `praw.ini `_ - -API Client/Connector (Prawcore Requestor) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Responsible for executing the actual HTTP requests to the Reddit API. It utilizes the base URL and user agent provided by the configuration and handles the low-level network communication. This component is part of the `prawcore` library, a core dependency of PRAW. - -**Related Classes/Methods**: - - -Authentication Module -^^^^^^^^^^^^^^^^^^^^^ - -Manages the various authentication flows required to interact with the Reddit API. It uses credentials (client ID, client secret, redirect URI) from the configuration to establish and maintain authenticated sessions. - -**Related Classes/Methods**: - - -Response Objector -^^^^^^^^^^^^^^^^^ - -Processes raw JSON responses received from the Reddit API, transforming them into structured PRAW-specific Python objects (e.g., `Comment`, `Submission`, `Redditor`). It also handles the parsing of API-specific errors. - -**Related Classes/Methods**: - -* `praw.objector.Objector:17-263 `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/.codeboarding/Object_Hydrator.json b/.codeboarding/Object_Hydrator.json deleted file mode 100644 index ec937306a..000000000 --- a/.codeboarding/Object_Hydrator.json +++ /dev/null @@ -1,68 +0,0 @@ -{ - "description": "The PRAW library's core functionality revolves around three main components: praw.Reddit (API Client), Objector, and PRAW Data Models. The praw.Reddit (API Client) serves as the primary interface for making requests to the Reddit API and receiving raw JSON responses. These raw responses are then passed to the Objector, which acts as a central factory and dispatcher. The Objector is responsible for parsing the JSON data, handling any API errors, and transforming the raw data into rich, interactive PRAW Data Models. These data models, such as Submission, Comment, and Redditor, encapsulate Reddit resources and provide a Pythonic way to interact with them, abstracting the underlying API complexities. This architecture ensures a clear separation of concerns, with the API client handling communication, the Objector managing data hydration, and the data models representing the structured Reddit resources.", - "components": [ - { - "name": "Objector", - "description": "The core component of the hydration process. It acts as a factory and dispatcher, orchestrating the conversion of raw JSON data from the Reddit API into rich PRAW model objects. It also handles error detection and parsing within the API response.", - "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 - } - ], - "can_expand": true - }, - { - "name": "praw.Reddit (API Client)", - "description": "This component represents the main entry point for interacting with the Reddit API. It is responsible for making HTTP requests, receiving raw JSON responses, and then delegating the processing of these responses to the Objector to convert them into PRAW models.", - "referenced_source_code": [ - { - "qualified_name": "praw.Reddit", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/__init__.py", - "reference_start_line": 13, - "reference_end_line": 13 - } - ], - "can_expand": true - }, - { - "name": "PRAW Data Models", - "description": "These are the rich, interactive Python objects that represent various Reddit resources (e.g., submissions, comments, users). They encapsulate the data and provide methods for interacting with those resources in a Pythonic way, abstracting the underlying API calls.", - "referenced_source_code": [ - { - "qualified_name": "praw.models.submission.Submission", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/submission.py", - "reference_start_line": 0, - "reference_end_line": 0 - }, - { - "qualified_name": "praw.models.comment.Comment", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/comment.py", - "reference_start_line": 0, - "reference_end_line": 0 - }, - { - "qualified_name": "praw.models.redditor.Redditor", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/redditor.py", - "reference_start_line": 0, - "reference_end_line": 0 - } - ], - "can_expand": true - } - ], - "components_relations": [ - { - "relation": "passes raw API responses to and depends on", - "src_name": "praw.Reddit (API Client)", - "dst_name": "Objector" - }, - { - "relation": "creates instances of", - "src_name": "Objector", - "dst_name": "PRAW Data Models" - } - ] -} diff --git a/.codeboarding/Object_Hydrator.rst b/.codeboarding/Object_Hydrator.rst deleted file mode 100644 index a85b8a27a..000000000 --- a/.codeboarding/Object_Hydrator.rst +++ /dev/null @@ -1,60 +0,0 @@ -Object Hydrator -=============== - -.. mermaid:: - - graph LR - Objector["Objector"] - praw_Reddit_API_Client_["praw.Reddit (API Client)"] - PRAW_Data_Models["PRAW Data Models"] - praw_Reddit_API_Client_ -- "passes raw API responses to and depends on" --> Objector - Objector -- "creates instances of" --> PRAW_Data_Models - -| |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 functionality revolves around three main components: praw.Reddit (API Client), Objector, and PRAW Data Models. The praw.Reddit (API Client) serves as the primary interface for making requests to the Reddit API and receiving raw JSON responses. These raw responses are then passed to the Objector, which acts as a central factory and dispatcher. The Objector is responsible for parsing the JSON data, handling any API errors, and transforming the raw data into rich, interactive PRAW Data Models. These data models, such as Submission, Comment, and Redditor, encapsulate Reddit resources and provide a Pythonic way to interact with them, abstracting the underlying API complexities. This architecture ensures a clear separation of concerns, with the API client handling communication, the Objector managing data hydration, and the data models representing the structured Reddit resources. - -Objector -^^^^^^^^ - -The core component of the hydration process. It acts as a factory and dispatcher, orchestrating the conversion of raw JSON data from the Reddit API into rich PRAW model objects. It also handles error detection and parsing within the API response. - -**Related Classes/Methods**: - -* `praw.objector.Objector:17-263 `_ - -praw.Reddit (API Client) -^^^^^^^^^^^^^^^^^^^^^^^^ - -This component represents the main entry point for interacting with the Reddit API. It is responsible for making HTTP requests, receiving raw JSON responses, and then delegating the processing of these responses to the Objector to convert them into PRAW models. - -**Related Classes/Methods**: - -* `praw.Reddit `_ - -PRAW Data Models -^^^^^^^^^^^^^^^^ - -These are the rich, interactive Python objects that represent various Reddit resources (e.g., submissions, comments, users). They encapsulate the data and provide methods for interacting with those resources in a Pythonic way, abstracting the underlying API calls. - -**Related Classes/Methods**: - -* `praw.models.submission.Submission `_ -* `praw.models.comment.Comment `_ -* `praw.models.redditor.Redditor `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/.codeboarding/Reddit_Data_Models.json b/.codeboarding/Reddit_Data_Models.json deleted file mode 100644 index d33dade71..000000000 --- a/.codeboarding/Reddit_Data_Models.json +++ /dev/null @@ -1,166 +0,0 @@ -{ - "description": "The PRAW `reddit.models` subsystem provides a structured object-oriented interface for interacting with the Reddit API. Core components like `Submission`, `Comment`, `Redditor`, and `Subreddit` serve as primary data models, encapsulating Reddit entities and their associated functionalities. These core models are augmented by specialized moderation components (`SubmissionModeration`, `CommentModeration`, `SubredditModeration`) that provide administrative capabilities, and stream components (`RedditorStream`) for accessing dynamic content. The system is designed around clear object relationships, where entities like `Subreddit` contain `Submission`s, and `Submission`s contain `Comment`s, facilitating intuitive navigation and interaction with Reddit data. Moderation components act directly upon their respective core entities, enabling a clear separation of concerns between data representation and administrative actions.", - "components": [ - { - "name": "Submission", - "description": "Represents a Reddit post, encapsulating its data (e.g., title, content, author, subreddit) and providing methods for interaction (e.g., voting, replying, editing). It serves as the primary interface for submission-specific data and actions.", - "referenced_source_code": [ - { - "qualified_name": "Submission", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/docs/examples/lmgtfy_bot.py", - "reference_start_line": 24, - "reference_end_line": 24 - } - ], - "can_expand": true - }, - { - "name": "Comment", - "description": "Represents a Reddit comment, managing its content, author, and position within a discussion thread. It provides methods for managing comment content and its hierarchical position.", - "referenced_source_code": [ - { - "qualified_name": "Comment", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", - "reference_start_line": 582, - "reference_end_line": 596 - } - ], - "can_expand": false - }, - { - "name": "Redditor", - "description": "Represents a Reddit user, offering access to their profile, activity history (e.g., submissions, comments), and relationships with other users or subreddits.", - "referenced_source_code": [ - { - "qualified_name": "Redditor", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", - "reference_start_line": 810, - "reference_end_line": 819 - } - ], - "can_expand": true - }, - { - "name": "Subreddit", - "description": "Represents a Reddit community, serving as a facade for managing subreddit settings, content, and user interactions within that community. It provides access to posts, moderation tools, and community-specific data.", - "referenced_source_code": [ - { - "qualified_name": "Subreddit", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/docs/examples/lmgtfy_bot.py", - "reference_start_line": 19, - "reference_end_line": 19 - } - ], - "can_expand": true - }, - { - "name": "SubmissionModeration", - "description": "Provides moderation functionalities specifically for a `Submission` object, enabling actions such as approving, removing, locking, or distinguishing posts.", - "referenced_source_code": [ - { - "qualified_name": "SubmissionModeration", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/submission.py", - "reference_start_line": 93, - "reference_end_line": 392 - } - ], - "can_expand": true - }, - { - "name": "CommentModeration", - "description": "Provides moderation functionalities specifically for a `Comment` object, enabling actions like approving, removing, or distinguishing comments.", - "referenced_source_code": [ - { - "qualified_name": "CommentModeration", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/comment.py", - "reference_start_line": 314, - "reference_end_line": 350 - } - ], - "can_expand": false - }, - { - "name": "RedditorStream", - "description": "Offers access to various streams of content related to a `Redditor`, such as their submissions, comments, or saved items, allowing for real-time or historical data retrieval.", - "referenced_source_code": [ - { - "qualified_name": "RedditorStream", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/redditor.py", - "reference_start_line": 412, - "reference_end_line": 457 - } - ], - "can_expand": false - }, - { - "name": "SubredditModeration", - "description": "Provides comprehensive moderation tools for a `Subreddit`, including managing users (e.g., banning, muting), flair, and content policies at the community level.", - "referenced_source_code": [ - { - "qualified_name": "SubredditModeration", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/user_subreddit.py", - "reference_start_line": 82, - "reference_end_line": 199 - } - ], - "can_expand": true - } - ], - "components_relations": [ - { - "relation": "contains", - "src_name": "Submission", - "dst_name": "Comment" - }, - { - "relation": "interacts with", - "src_name": "Submission", - "dst_name": "SubmissionModeration" - }, - { - "relation": "associated with", - "src_name": "Comment", - "dst_name": "Submission" - }, - { - "relation": "interacts with", - "src_name": "Comment", - "dst_name": "CommentModeration" - }, - { - "relation": "provides access to", - "src_name": "Redditor", - "dst_name": "RedditorStream" - }, - { - "relation": "contains", - "src_name": "Subreddit", - "dst_name": "Submission" - }, - { - "relation": "interacts with", - "src_name": "Subreddit", - "dst_name": "SubredditModeration" - }, - { - "relation": "acts upon", - "src_name": "SubmissionModeration", - "dst_name": "Submission" - }, - { - "relation": "acts upon", - "src_name": "CommentModeration", - "dst_name": "Comment" - }, - { - "relation": "provides data streams related to", - "src_name": "RedditorStream", - "dst_name": "Redditor" - }, - { - "relation": "acts upon", - "src_name": "SubredditModeration", - "dst_name": "Subreddit" - } - ] -} diff --git a/.codeboarding/Reddit_Data_Models.rst b/.codeboarding/Reddit_Data_Models.rst deleted file mode 100644 index 0ffbe344a..000000000 --- a/.codeboarding/Reddit_Data_Models.rst +++ /dev/null @@ -1,117 +0,0 @@ -Reddit Data Models -================== - -.. mermaid:: - - graph LR - Submission["Submission"] - Comment["Comment"] - Redditor["Redditor"] - Subreddit["Subreddit"] - SubmissionModeration["SubmissionModeration"] - CommentModeration["CommentModeration"] - RedditorStream["RedditorStream"] - SubredditModeration["SubredditModeration"] - Submission -- "contains" --> Comment - Submission -- "interacts with" --> SubmissionModeration - Comment -- "associated with" --> Submission - Comment -- "interacts with" --> CommentModeration - Redditor -- "provides access to" --> RedditorStream - Subreddit -- "contains" --> Submission - Subreddit -- "interacts with" --> SubredditModeration - SubmissionModeration -- "acts upon" --> Submission - CommentModeration -- "acts upon" --> Comment - RedditorStream -- "provides data streams related to" --> Redditor - SubredditModeration -- "acts upon" --> Subreddit - -| |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 `reddit.models` subsystem provides a structured object-oriented interface for interacting with the Reddit API. Core components like `Submission`, `Comment`, `Redditor`, and `Subreddit` serve as primary data models, encapsulating Reddit entities and their associated functionalities. These core models are augmented by specialized moderation components (`SubmissionModeration`, `CommentModeration`, `SubredditModeration`) that provide administrative capabilities, and stream components (`RedditorStream`) for accessing dynamic content. The system is designed around clear object relationships, where entities like `Subreddit` contain `Submission`s, and `Submission`s contain `Comment`s, facilitating intuitive navigation and interaction with Reddit data. Moderation components act directly upon their respective core entities, enabling a clear separation of concerns between data representation and administrative actions. - -Submission -^^^^^^^^^^ - -Represents a Reddit post, encapsulating its data (e.g., title, content, author, subreddit) and providing methods for interaction (e.g., voting, replying, editing). It serves as the primary interface for submission-specific data and actions. - -**Related Classes/Methods**: - -* `Submission `_ - -Comment -^^^^^^^ - -Represents a Reddit comment, managing its content, author, and position within a discussion thread. It provides methods for managing comment content and its hierarchical position. - -**Related Classes/Methods**: - -* `Comment:582-596 `_ - -Redditor -^^^^^^^^ - -Represents a Reddit user, offering access to their profile, activity history (e.g., submissions, comments), and relationships with other users or subreddits. - -**Related Classes/Methods**: - -* `Redditor:810-819 `_ - -Subreddit -^^^^^^^^^ - -Represents a Reddit community, serving as a facade for managing subreddit settings, content, and user interactions within that community. It provides access to posts, moderation tools, and community-specific data. - -**Related Classes/Methods**: - -* `Subreddit `_ - -SubmissionModeration -^^^^^^^^^^^^^^^^^^^^ - -Provides moderation functionalities specifically for a `Submission` object, enabling actions such as approving, removing, locking, or distinguishing posts. - -**Related Classes/Methods**: - -* `SubmissionModeration:93-392 `_ - -CommentModeration -^^^^^^^^^^^^^^^^^ - -Provides moderation functionalities specifically for a `Comment` object, enabling actions like approving, removing, or distinguishing comments. - -**Related Classes/Methods**: - -* `CommentModeration:314-350 `_ - -RedditorStream -^^^^^^^^^^^^^^ - -Offers access to various streams of content related to a `Redditor`, such as their submissions, comments, or saved items, allowing for real-time or historical data retrieval. - -**Related Classes/Methods**: - -* `RedditorStream:412-457 `_ - -SubredditModeration -^^^^^^^^^^^^^^^^^^^ - -Provides comprehensive moderation tools for a `Subreddit`, including managing users (e.g., banning, muting), flair, and content policies at the community level. - -**Related Classes/Methods**: - -* `SubredditModeration:82-199 `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/.codeboarding/analysis.json b/.codeboarding/analysis.json deleted file mode 100644 index 100cb1fae..000000000 --- a/.codeboarding/analysis.json +++ /dev/null @@ -1,176 +0,0 @@ -{ - "description": "PRAW (Python Reddit API Wrapper) is structured around a clear separation of concerns, facilitating robust and flexible interaction with the Reddit API. At its core, the API Client Core (`praw.reddit.Reddit`) serves as the central communication hub, managing all HTTP requests, authentication, and rate limiting. It relies on the Configuration Manager (`praw.config.Config`) to load and provide necessary settings, ensuring proper API access.\n\nUpon receiving raw JSON responses from the Reddit API, the API Client Core forwards this data to the Object Hydrator (`praw.objector.Objector`). The Object Hydrator is responsible for transforming these generic JSON structures into rich, interactive Python objects, which are instances of the Reddit Data Models (e.g., `praw.models.reddit.submission.Submission`, `praw.models.reddit.comment.Comment`, `praw.models.reddit.redditor.Redditor`, `praw.models.reddit.subreddit.Subreddit`). These models encapsulate Reddit entities and provide methods for further interaction.\n\nTo simplify complex API operations, API Interaction Facades provide high-level, domain-specific interfaces. These facades, such as `praw.models.listing.generator.ListingGenerator` for listing content, `praw.models.util.stream_generator` for streaming, and various methods within `praw.models.reddit.subreddit.Subreddit`, `praw.models.reddit.modmail`, `praw.models.mod_notes`, `praw.models.reddit.redditor.Redditor`, and `praw.models.auth.Auth`, abstract the underlying API calls. They send requests through the API Client Core and operate on the Reddit Data Models, allowing developers to interact with Reddit entities in an intuitive, object-oriented manner. The Reddit Data Models themselves can also initiate requests back through the API Client Core for entity-specific actions.", - "components": [ - { - "name": "API Client Core", - "description": "The central component for all Reddit API communication, handling HTTP requests, authentication, and rate limiting. It acts as the primary interface for other components to communicate with Reddit.", - "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 - } - ], - "can_expand": true - }, - { - "name": "Configuration Manager", - "description": "Responsible for loading, parsing, and providing PRAW's configuration settings from various sources (e.g., `praw.ini`, environment variables).", - "referenced_source_code": [ - { - "qualified_name": "praw.config.Config", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/config.py", - "reference_start_line": 52, - "reference_end_line": 52 - } - ], - "can_expand": true - }, - { - "name": "Object Hydrator", - "description": "Transforms raw JSON data received from the Reddit API into rich, interactive Python objects (PRAW models), converting generic API responses into type-safe and method-rich objects.", - "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 - } - ], - "can_expand": true - }, - { - "name": "Reddit Data Models", - "description": "A comprehensive collection of classes representing various Reddit entities (e.g., `Submission`, `Comment`, `Redditor`, `Subreddit`). These objects encapsulate data and provide entity-specific methods for interaction.", - "referenced_source_code": [ - { - "qualified_name": "praw.models.reddit.submission.Submission", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/submission.py", - "reference_start_line": 716, - "reference_end_line": 716 - }, - { - "qualified_name": "praw.models.reddit.comment.Comment", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/comment.py", - "reference_start_line": 328, - "reference_end_line": 328 - }, - { - "qualified_name": "praw.models.reddit.redditor.Redditor", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/redditor.py", - "reference_start_line": 421, - "reference_end_line": 421 - }, - { - "qualified_name": "praw.models.reddit.subreddit.Subreddit", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/subreddit.py", - "reference_start_line": 2446, - "reference_end_line": 2446 - } - ], - "can_expand": true - }, - { - "name": "API Interaction Facades", - "description": "Provides high-level, domain-specific interfaces for interacting with the Reddit API, abstracting complex operations and data retrieval patterns. This component groups functionalities like listing/streaming, subreddit management, moderation tools, and user/authentication specific actions.", - "referenced_source_code": [ - { - "qualified_name": "praw.models.listing.generator.ListingGenerator", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py", - "reference_start_line": 17, - "reference_end_line": 103 - }, - { - "qualified_name": "praw.models.util.stream_generator", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/util.py", - "reference_start_line": 36, - "reference_end_line": 163 - }, - { - "qualified_name": "praw.models.reddit.subreddit.Subreddit", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/subreddit.py", - "reference_start_line": 2446, - "reference_end_line": 2446 - }, - { - "qualified_name": "praw.models.reddit.modmail", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/modmail.py", - "reference_start_line": 0, - "reference_end_line": 0 - }, - { - "qualified_name": "praw.models.mod_notes", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/mod_notes.py", - "reference_start_line": 0, - "reference_end_line": 0 - }, - { - "qualified_name": "praw.models.reddit.redditor.Redditor", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/redditor.py", - "reference_start_line": 421, - "reference_end_line": 421 - }, - { - "qualified_name": "praw.models.auth.Auth", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/auth.py", - "reference_start_line": 11, - "reference_end_line": 125 - } - ], - "can_expand": true - } - ], - "components_relations": [ - { - "relation": "provides settings to", - "src_name": "Configuration Manager", - "dst_name": "API Client Core" - }, - { - "relation": "reads configuration from", - "src_name": "API Client Core", - "dst_name": "Configuration Manager" - }, - { - "relation": "sends requests via", - "src_name": "API Interaction Facades", - "dst_name": "API Client Core" - }, - { - "relation": "executes actions for", - "src_name": "API Client Core", - "dst_name": "API Interaction Facades" - }, - { - "relation": "sends raw API response to", - "src_name": "API Client Core", - "dst_name": "Object Hydrator" - }, - { - "relation": "returns PRAW objects to", - "src_name": "Object Hydrator", - "dst_name": "API Client Core" - }, - { - "relation": "creates and populates", - "src_name": "API Client Core", - "dst_name": "Reddit Data Models" - }, - { - "relation": "operates on", - "src_name": "API Interaction Facades", - "dst_name": "Reddit Data Models" - }, - { - "relation": "are managed by", - "src_name": "Reddit Data Models", - "dst_name": "API Interaction Facades" - }, - { - "relation": "initiate requests via", - "src_name": "Reddit Data Models", - "dst_name": "API Client Core" - } - ] -} diff --git a/.codeboarding/codeboarding_version.json b/.codeboarding/codeboarding_version.json deleted file mode 100644 index 89e257292..000000000 --- a/.codeboarding/codeboarding_version.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "commit_hash": "3a1249a579ce1b58816a4e74ae7ffa22e28042ae", - "code_boarding_version": "0.1.0" -} diff --git a/.codeboarding/overview.rst b/.codeboarding/overview.rst deleted file mode 100644 index 71d037ebb..000000000 --- a/.codeboarding/overview.rst +++ /dev/null @@ -1,114 +0,0 @@ -Overview -======== - -.. mermaid:: - - graph LR - API_Client_Core["API Client Core"] - Configuration_Manager["Configuration Manager"] - Object_Hydrator["Object Hydrator"] - Reddit_Data_Models["Reddit Data Models"] - API_Interaction_Facades["API Interaction Facades"] - Configuration_Manager -- "provides settings to" --> API_Client_Core - API_Client_Core -- "reads configuration from" --> Configuration_Manager - API_Interaction_Facades -- "sends requests via" --> API_Client_Core - API_Client_Core -- "executes actions for" --> API_Interaction_Facades - API_Client_Core -- "sends raw API response to" --> Object_Hydrator - Object_Hydrator -- "returns PRAW objects to" --> API_Client_Core - API_Client_Core -- "creates and populates" --> Reddit_Data_Models - API_Interaction_Facades -- "operates on" --> Reddit_Data_Models - Reddit_Data_Models -- "are managed by" --> API_Interaction_Facades - Reddit_Data_Models -- "initiate requests via" --> API_Client_Core - click API_Client_Core href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/API_Client_Core.html" "Details" - click Configuration_Manager href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Configuration_Manager.html" "Details" - click Object_Hydrator href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Object_Hydrator.html" "Details" - click Reddit_Data_Models href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/Reddit_Data_Models.html" "Details" - click API_Interaction_Facades href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/API_Interaction_Facades.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 -------- - -PRAW (Python Reddit API Wrapper) is structured around a clear separation of concerns, facilitating robust and flexible interaction with the Reddit API. At its core, the API Client Core (`praw.reddit.Reddit`) serves as the central communication hub, managing all HTTP requests, authentication, and rate limiting. It relies on the Configuration Manager (`praw.config.Config`) to load and provide necessary settings, ensuring proper API access. - -Upon receiving raw JSON responses from the Reddit API, the API Client Core forwards this data to the Object Hydrator (`praw.objector.Objector`). The Object Hydrator is responsible for transforming these generic JSON structures into rich, interactive Python objects, which are instances of the Reddit Data Models (e.g., `praw.models.reddit.submission.Submission`, `praw.models.reddit.comment.Comment`, `praw.models.reddit.redditor.Redditor`, `praw.models.reddit.subreddit.Subreddit`). These models encapsulate Reddit entities and provide methods for further interaction. - -To simplify complex API operations, API Interaction Facades provide high-level, domain-specific interfaces. These facades, such as `praw.models.listing.generator.ListingGenerator` for listing content, `praw.models.util.stream_generator` for streaming, and various methods within `praw.models.reddit.subreddit.Subreddit`, `praw.models.reddit.modmail`, `praw.models.mod_notes`, `praw.models.reddit.redditor.Redditor`, and `praw.models.auth.Auth`, abstract the underlying API calls. They send requests through the API Client Core and operate on the Reddit Data Models, allowing developers to interact with Reddit entities in an intuitive, object-oriented manner. The Reddit Data Models themselves can also initiate requests back through the API Client Core for entity-specific actions. - -API Client Core -^^^^^^^^^^^^^^^ - -:ref:`Expand ` - -The central component for all Reddit API communication, handling HTTP requests, authentication, and rate limiting. It acts as the primary interface for other components to communicate with Reddit. - -**Related Classes/Methods**: - -* `praw.reddit.Reddit:57-901 `_ - -Configuration Manager -^^^^^^^^^^^^^^^^^^^^^ - -:ref:`Expand ` - -Responsible for loading, parsing, and providing PRAW's configuration settings from various sources (e.g., `praw.ini`, environment variables). - -**Related Classes/Methods**: - -* `praw.config.Config `_ - -Object Hydrator -^^^^^^^^^^^^^^^ - -:ref:`Expand ` - -Transforms raw JSON data received from the Reddit API into rich, interactive Python objects (PRAW models), converting generic API responses into type-safe and method-rich objects. - -**Related Classes/Methods**: - -* `praw.objector.Objector:17-263 `_ - -Reddit Data Models -^^^^^^^^^^^^^^^^^^ - -:ref:`Expand ` - -A comprehensive collection of classes representing various Reddit entities (e.g., `Submission`, `Comment`, `Redditor`, `Subreddit`). These objects encapsulate data and provide entity-specific methods for interaction. - -**Related Classes/Methods**: - -* `praw.models.reddit.submission.Submission `_ -* `praw.models.reddit.comment.Comment `_ -* `praw.models.reddit.redditor.Redditor `_ -* `praw.models.reddit.subreddit.Subreddit `_ - -API Interaction Facades -^^^^^^^^^^^^^^^^^^^^^^^ - -:ref:`Expand ` - -Provides high-level, domain-specific interfaces for interacting with the Reddit API, abstracting complex operations and data retrieval patterns. This component groups functionalities like listing/streaming, subreddit management, moderation tools, and user/authentication specific actions. - -**Related Classes/Methods**: - -* `praw.models.listing.generator.ListingGenerator:17-103 `_ -* `praw.models.util.stream_generator:36-163 `_ -* `praw.models.reddit.subreddit.Subreddit `_ -* `praw.models.reddit.modmail `_ -* `praw.models.mod_notes `_ -* `praw.models.reddit.redditor.Redditor `_ -* `praw.models.auth.Auth:11-125 `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/.github/workflows/docs_codeboarding.yml b/.github/workflows/docs_codeboarding.yml index 1aa8613cf..04f1a9d05 100644 --- a/.github/workflows/docs_codeboarding.yml +++ b/.github/workflows/docs_codeboarding.yml @@ -87,32 +87,32 @@ jobs: echo "JSON directory: ${{ steps.codeboarding.outputs.json_directory }}" echo "Has changes: ${{ steps.codeboarding.outputs.has_changes }}" - # Move .rst files from docs/architecture_overview/ to .codeboarding folder - - name: Move architecture overview .rst files + # Move .rst files from .codeboarding/ to docs/architecture_overview/ folder + - name: Move .rst files to architecture overview run: | - # Create .codeboarding directory if it doesn't exist - mkdir -p .codeboarding + # Create docs/architecture_overview directory if it doesn't exist + mkdir -p docs/architecture_overview - # Check if docs/architecture_overview/ exists and contains .rst files - if [ -d "docs/architecture_overview" ] && [ -n "$(find docs/architecture_overview -name '*.rst' -type f)" ]; then - echo "Moving .rst files from docs/architecture_overview/ to .codeboarding/" + # 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 .codeboarding folder - cp docs/architecture_overview/*.rst .codeboarding/ 2>/dev/null || echo "No .rst files found to copy" + # 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 docs/architecture_overview -type d -exec sh -c ' + 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 .codeboarding/ 2>/dev/null || echo "No .rst files found in $dir" + cp "$dir"/*.rst docs/architecture_overview/ 2>/dev/null || echo "No .rst files found in $dir" fi done ' sh {} + - echo "Architecture overview .rst files moved successfully" + echo ".rst files moved to architecture overview successfully" else - echo "No docs/architecture_overview/ directory or .rst files found" + echo "No .codeboarding/ directory or .rst files found" fi # Check if we have any changes to commit From ee31f5b0cb1cad4e4004de071d7113e6be7d40ec Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Mon, 1 Sep 2025 19:19:28 +0000 Subject: [PATCH 13/23] docs: update codeboarding documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 📚 Documentation Update This commit contains updated documentation files fetched from the CodeBoarding service. ### 📊 Summary - Documentation files created/updated: 6 - JSON files created/updated: 7 - Documentation directory: .codeboarding/ - JSON directory: .codeboarding/ - Output format: .rst - Repository analyzed: https://github.com/CodeBoarding/praw - Source branch: main - Target branch: main 🤖 This commit was automatically generated by the CodeBoarding documentation update workflow. --- .codeboarding/Listing_Streaming.json | 151 ++++++++++++ .codeboarding/Listing_Streaming.rst | 114 +++++++++ .codeboarding/Low_Level_API_Connector.json | 123 ++++++++++ .codeboarding/Low_Level_API_Connector.rst | 92 +++++++ .codeboarding/Object_Transformer.json | 107 ++++++++ .codeboarding/Object_Transformer.rst | 83 +++++++ .codeboarding/Reddit_Client.json | 230 ++++++++++++++++++ .codeboarding/Reddit_Client.rst | 112 +++++++++ .codeboarding/Reddit_Data_Models.json | 121 +++++++++ .codeboarding/Reddit_Data_Models.rst | 108 ++++++++ .codeboarding/analysis.json | 125 ++++++++++ .codeboarding/codeboarding_version.json | 4 + .codeboarding/overview.rst | 109 +++++++++ .../Listing_Streaming.rst | 114 +++++++++ .../Low_Level_API_Connector.rst | 92 +++++++ .../Object_Transformer.rst | 83 +++++++ docs/architecture_overview/Reddit_Client.rst | 112 +++++++++ .../Reddit_Data_Models.rst | 108 ++++++++ docs/architecture_overview/overview.rst | 109 +++++++++ 19 files changed, 2097 insertions(+) create mode 100644 .codeboarding/Listing_Streaming.json create mode 100644 .codeboarding/Listing_Streaming.rst create mode 100644 .codeboarding/Low_Level_API_Connector.json create mode 100644 .codeboarding/Low_Level_API_Connector.rst create mode 100644 .codeboarding/Object_Transformer.json create mode 100644 .codeboarding/Object_Transformer.rst create mode 100644 .codeboarding/Reddit_Client.json create mode 100644 .codeboarding/Reddit_Client.rst create mode 100644 .codeboarding/Reddit_Data_Models.json create mode 100644 .codeboarding/Reddit_Data_Models.rst create mode 100644 .codeboarding/analysis.json create mode 100644 .codeboarding/codeboarding_version.json create mode 100644 .codeboarding/overview.rst create mode 100644 docs/architecture_overview/Listing_Streaming.rst create mode 100644 docs/architecture_overview/Low_Level_API_Connector.rst create mode 100644 docs/architecture_overview/Object_Transformer.rst create mode 100644 docs/architecture_overview/Reddit_Client.rst create mode 100644 docs/architecture_overview/Reddit_Data_Models.rst create mode 100644 docs/architecture_overview/overview.rst diff --git a/.codeboarding/Listing_Streaming.json b/.codeboarding/Listing_Streaming.json new file mode 100644 index 000000000..9a11a7f20 --- /dev/null +++ b/.codeboarding/Listing_Streaming.json @@ -0,0 +1,151 @@ +{ + "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 + } + ], + "can_expand": true + }, + { + "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 + } + ], + "can_expand": false + }, + { + "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 + } + ], + "can_expand": false + }, + { + "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 + } + ], + "can_expand": true + }, + { + "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 + } + ], + "can_expand": true + }, + { + "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 + } + ], + "can_expand": true + }, + { + "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 + } + ], + "can_expand": true + }, + { + "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 + } + ], + "can_expand": false + } + ], + "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..4f4e2b01d --- /dev/null +++ b/.codeboarding/Listing_Streaming.rst @@ -0,0 +1,114 @@ +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 `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/.codeboarding/Low_Level_API_Connector.json b/.codeboarding/Low_Level_API_Connector.json new file mode 100644 index 000000000..6603b1a3e --- /dev/null +++ b/.codeboarding/Low_Level_API_Connector.json @@ -0,0 +1,123 @@ +{ + "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 + } + ], + "can_expand": true + }, + { + "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 + } + ], + "can_expand": true + }, + { + "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 + } + ], + "can_expand": true + }, + { + "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 + } + ], + "can_expand": true + }, + { + "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 + } + ], + "can_expand": true + } + ], + "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..8c303a1ba --- /dev/null +++ b/.codeboarding/Low_Level_API_Connector.rst @@ -0,0 +1,92 @@ +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 `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/.codeboarding/Object_Transformer.json b/.codeboarding/Object_Transformer.json new file mode 100644 index 000000000..f3bdc4050 --- /dev/null +++ b/.codeboarding/Object_Transformer.json @@ -0,0 +1,107 @@ +{ + "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 + } + ], + "can_expand": true + }, + { + "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 + } + ], + "can_expand": false + }, + { + "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 + } + ], + "can_expand": true + }, + { + "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 + } + ], + "can_expand": false + }, + { + "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 + } + ], + "can_expand": false + } + ], + "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..61a90b2dd --- /dev/null +++ b/.codeboarding/Object_Transformer.rst @@ -0,0 +1,83 @@ +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 `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/.codeboarding/Reddit_Client.json b/.codeboarding/Reddit_Client.json new file mode 100644 index 000000000..574eeab46 --- /dev/null +++ b/.codeboarding/Reddit_Client.json @@ -0,0 +1,230 @@ +{ + "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 + } + ], + "can_expand": true + }, + { + "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 + } + ], + "can_expand": false + }, + { + "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 + } + ], + "can_expand": true + }, + { + "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 + } + ], + "can_expand": true + }, + { + "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 + } + ], + "can_expand": true + }, + { + "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 + } + ], + "can_expand": true + } + ], + "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..ecc44610d --- /dev/null +++ b/.codeboarding/Reddit_Client.rst @@ -0,0 +1,112 @@ +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 `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/.codeboarding/Reddit_Data_Models.json b/.codeboarding/Reddit_Data_Models.json new file mode 100644 index 000000000..72436d5b4 --- /dev/null +++ b/.codeboarding/Reddit_Data_Models.json @@ -0,0 +1,121 @@ +{ + "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 + } + ], + "can_expand": true + }, + { + "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 + } + ], + "can_expand": true + }, + { + "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 + } + ], + "can_expand": false + }, + { + "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 + } + ], + "can_expand": false + }, + { + "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 + } + ], + "can_expand": true + }, + { + "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 + } + ], + "can_expand": true + }, + { + "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 + } + ], + "can_expand": false + }, + { + "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 + } + ], + "can_expand": false + } + ], + "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..58a6cacea --- /dev/null +++ b/.codeboarding/Reddit_Data_Models.rst @@ -0,0 +1,108 @@ +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 `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/.codeboarding/analysis.json b/.codeboarding/analysis.json new file mode 100644 index 000000000..71209b3a9 --- /dev/null +++ b/.codeboarding/analysis.json @@ -0,0 +1,125 @@ +{ + "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 + } + ], + "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 + } + ], + "can_expand": false + }, + { + "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 + } + ], + "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 + } + ], + "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 + } + ], + "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 + } + ], + "can_expand": true + } + ], + "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..94c718b63 --- /dev/null +++ b/.codeboarding/codeboarding_version.json @@ -0,0 +1,4 @@ +{ + "commit_hash": "6b3fa897303d414ede32c3788db04b0fcd124e37", + "code_boarding_version": "0.1.0" +} diff --git a/.codeboarding/overview.rst b/.codeboarding/overview.rst new file mode 100644 index 000000000..f0514e5a9 --- /dev/null +++ b/.codeboarding/overview.rst @@ -0,0 +1,109 @@ +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"] + 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 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 +^^^^^^^^^^^^^^^^^^^^^ + +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 `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/docs/architecture_overview/Listing_Streaming.rst b/docs/architecture_overview/Listing_Streaming.rst new file mode 100644 index 000000000..4f4e2b01d --- /dev/null +++ b/docs/architecture_overview/Listing_Streaming.rst @@ -0,0 +1,114 @@ +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 `_ + + +FAQ +--- + +`See the FAQ `_ 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..8c303a1ba --- /dev/null +++ b/docs/architecture_overview/Low_Level_API_Connector.rst @@ -0,0 +1,92 @@ +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 `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/docs/architecture_overview/Object_Transformer.rst b/docs/architecture_overview/Object_Transformer.rst new file mode 100644 index 000000000..61a90b2dd --- /dev/null +++ b/docs/architecture_overview/Object_Transformer.rst @@ -0,0 +1,83 @@ +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 `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/docs/architecture_overview/Reddit_Client.rst b/docs/architecture_overview/Reddit_Client.rst new file mode 100644 index 000000000..ecc44610d --- /dev/null +++ b/docs/architecture_overview/Reddit_Client.rst @@ -0,0 +1,112 @@ +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 `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/docs/architecture_overview/Reddit_Data_Models.rst b/docs/architecture_overview/Reddit_Data_Models.rst new file mode 100644 index 000000000..58a6cacea --- /dev/null +++ b/docs/architecture_overview/Reddit_Data_Models.rst @@ -0,0 +1,108 @@ +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 `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/docs/architecture_overview/overview.rst b/docs/architecture_overview/overview.rst new file mode 100644 index 000000000..f0514e5a9 --- /dev/null +++ b/docs/architecture_overview/overview.rst @@ -0,0 +1,109 @@ +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"] + 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 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 +^^^^^^^^^^^^^^^^^^^^^ + +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 `_ + + +FAQ +--- + +`See the FAQ `_ From 734fc8210fab62790205e92d961573c16ff8d893 Mon Sep 17 00:00:00 2001 From: ivanmilevtues Date: Mon, 1 Sep 2025 21:29:16 +0200 Subject: [PATCH 14/23] adding readdocs integration --- .codeboarding/Listing_Streaming.rst | 6 ------ .codeboarding/Low_Level_API_Connector.rst | 6 ------ .codeboarding/Object_Transformer.rst | 6 ------ .codeboarding/Reddit_Client.rst | 6 ------ .codeboarding/Reddit_Data_Models.rst | 6 ------ .codeboarding/overview.rst | 6 ------ docs/architecture_overview/Listing_Streaming.rst | 6 ------ docs/architecture_overview/Low_Level_API_Connector.rst | 6 ------ docs/architecture_overview/Object_Transformer.rst | 6 ------ docs/architecture_overview/Reddit_Client.rst | 6 ------ docs/architecture_overview/overview.rst | 6 ------ docs/index.rst | 7 ++++--- 12 files changed, 4 insertions(+), 69 deletions(-) diff --git a/.codeboarding/Listing_Streaming.rst b/.codeboarding/Listing_Streaming.rst index 4f4e2b01d..ff41e468c 100644 --- a/.codeboarding/Listing_Streaming.rst +++ b/.codeboarding/Listing_Streaming.rst @@ -106,9 +106,3 @@ Represents the `stream` method within the `Subreddits` class, providing access t **Related Classes/Methods**: * `Subreddits.stream:124-133 `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/.codeboarding/Low_Level_API_Connector.rst b/.codeboarding/Low_Level_API_Connector.rst index 8c303a1ba..62dcdc029 100644 --- a/.codeboarding/Low_Level_API_Connector.rst +++ b/.codeboarding/Low_Level_API_Connector.rst @@ -84,9 +84,3 @@ Handles the loading, parsing, and management of configuration settings (e.g., cl **Related Classes/Methods**: * `praw.config `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/.codeboarding/Object_Transformer.rst b/.codeboarding/Object_Transformer.rst index 61a90b2dd..0da8a3e3a 100644 --- a/.codeboarding/Object_Transformer.rst +++ b/.codeboarding/Object_Transformer.rst @@ -75,9 +75,3 @@ Extracts and formats detailed error messages from the raw API response, converti **Related Classes/Methods**: * `praw.objector.Objector:parse_error `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/.codeboarding/Reddit_Client.rst b/.codeboarding/Reddit_Client.rst index ecc44610d..2bffa1895 100644 --- a/.codeboarding/Reddit_Client.rst +++ b/.codeboarding/Reddit_Client.rst @@ -104,9 +104,3 @@ Monitors and enforces Reddit API rate limits. It pauses requests when necessary **Related Classes/Methods**: * `praw.reddit.Reddit:_handle_rate_limit `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/.codeboarding/Reddit_Data_Models.rst b/.codeboarding/Reddit_Data_Models.rst index 58a6cacea..d51b2750b 100644 --- a/.codeboarding/Reddit_Data_Models.rst +++ b/.codeboarding/Reddit_Data_Models.rst @@ -100,9 +100,3 @@ Manages post collections within a subreddit, providing an interface for creating **Related Classes/Methods**: * `praw.models.reddit.collections `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/.codeboarding/overview.rst b/.codeboarding/overview.rst index f0514e5a9..e34b3e868 100644 --- a/.codeboarding/overview.rst +++ b/.codeboarding/overview.rst @@ -101,9 +101,3 @@ Provides mechanisms for efficiently retrieving and iterating over collections of **Related Classes/Methods**: * `praw.models.listing `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/docs/architecture_overview/Listing_Streaming.rst b/docs/architecture_overview/Listing_Streaming.rst index 4f4e2b01d..ff41e468c 100644 --- a/docs/architecture_overview/Listing_Streaming.rst +++ b/docs/architecture_overview/Listing_Streaming.rst @@ -106,9 +106,3 @@ Represents the `stream` method within the `Subreddits` class, providing access t **Related Classes/Methods**: * `Subreddits.stream:124-133 `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/docs/architecture_overview/Low_Level_API_Connector.rst b/docs/architecture_overview/Low_Level_API_Connector.rst index 8c303a1ba..62dcdc029 100644 --- a/docs/architecture_overview/Low_Level_API_Connector.rst +++ b/docs/architecture_overview/Low_Level_API_Connector.rst @@ -84,9 +84,3 @@ Handles the loading, parsing, and management of configuration settings (e.g., cl **Related Classes/Methods**: * `praw.config `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/docs/architecture_overview/Object_Transformer.rst b/docs/architecture_overview/Object_Transformer.rst index 61a90b2dd..0da8a3e3a 100644 --- a/docs/architecture_overview/Object_Transformer.rst +++ b/docs/architecture_overview/Object_Transformer.rst @@ -75,9 +75,3 @@ Extracts and formats detailed error messages from the raw API response, converti **Related Classes/Methods**: * `praw.objector.Objector:parse_error `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/docs/architecture_overview/Reddit_Client.rst b/docs/architecture_overview/Reddit_Client.rst index ecc44610d..2bffa1895 100644 --- a/docs/architecture_overview/Reddit_Client.rst +++ b/docs/architecture_overview/Reddit_Client.rst @@ -104,9 +104,3 @@ Monitors and enforces Reddit API rate limits. It pauses requests when necessary **Related Classes/Methods**: * `praw.reddit.Reddit:_handle_rate_limit `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/docs/architecture_overview/overview.rst b/docs/architecture_overview/overview.rst index f0514e5a9..e34b3e868 100644 --- a/docs/architecture_overview/overview.rst +++ b/docs/architecture_overview/overview.rst @@ -101,9 +101,3 @@ Provides mechanisms for efficiently retrieving and iterating over collections of **Related Classes/Methods**: * `praw.models.listing `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/docs/index.rst b/docs/index.rst index 8e974e9c0..89cf28449 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -49,10 +49,11 @@ application. See :ref:`oauth` for information on using **installed** application :caption: Architecture Overview architecture_overview/overview - architecture_overview/API_Client_Core - architecture_overview/Object_Transformation_Layer + architecture_overview/Listing_Streaming + architecture_overview/Low_Level_API_Connector + architecture_overview/Object_Transformer architecture_overview/Reddit_Data_Models - architecture_overview/Listing_Stream_Processors + architecture_overview/Reddit_Client .. _tutorial: From 243a716baa5f6ac1bcc5be3b6cf546c27d166d90 Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Mon, 1 Sep 2025 19:32:44 +0000 Subject: [PATCH 15/23] docs: update codeboarding documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 📚 Documentation Update This commit contains updated documentation files fetched from the CodeBoarding service. ### 📊 Summary - Documentation files created/updated: 6 - JSON files created/updated: 7 - Documentation directory: .codeboarding/ - JSON directory: .codeboarding/ - Output format: .rst - Repository analyzed: https://github.com/CodeBoarding/praw - Source branch: main - Target branch: main 🤖 This commit was automatically generated by the CodeBoarding documentation update workflow. --- .codeboarding/Listing_Streaming.json | 24 +++++++------------ .codeboarding/Listing_Streaming.rst | 6 +++++ .codeboarding/Low_Level_API_Connector.json | 15 ++++-------- .codeboarding/Low_Level_API_Connector.rst | 6 +++++ .codeboarding/Object_Transformer.json | 15 ++++-------- .codeboarding/Object_Transformer.rst | 6 +++++ .codeboarding/Reddit_Client.json | 18 +++++--------- .codeboarding/Reddit_Client.rst | 6 +++++ .codeboarding/Reddit_Data_Models.json | 24 +++++++------------ .codeboarding/Reddit_Data_Models.rst | 6 +++++ .codeboarding/codeboarding_version.json | 2 +- .codeboarding/overview.rst | 6 +++++ .../Listing_Streaming.rst | 6 +++++ .../Low_Level_API_Connector.rst | 6 +++++ .../Object_Transformer.rst | 6 +++++ docs/architecture_overview/Reddit_Client.rst | 6 +++++ docs/architecture_overview/overview.rst | 6 +++++ 17 files changed, 99 insertions(+), 65 deletions(-) diff --git a/.codeboarding/Listing_Streaming.json b/.codeboarding/Listing_Streaming.json index 9a11a7f20..0918a2a22 100644 --- a/.codeboarding/Listing_Streaming.json +++ b/.codeboarding/Listing_Streaming.json @@ -11,8 +11,7 @@ "reference_start_line": 17, "reference_end_line": 103 } - ], - "can_expand": true + ] }, { "name": "BaseListingMixin", @@ -24,8 +23,7 @@ "reference_start_line": 15, "reference_end_line": 149 } - ], - "can_expand": false + ] }, { "name": "SubredditListingMixin", @@ -37,8 +35,7 @@ "reference_start_line": 49, "reference_end_line": 73 } - ], - "can_expand": false + ] }, { "name": "RedditorListingMixin", @@ -50,8 +47,7 @@ "reference_start_line": 35, "reference_end_line": 185 } - ], - "can_expand": true + ] }, { "name": "StreamGenerator", @@ -63,8 +59,7 @@ "reference_start_line": 36, "reference_end_line": 163 } - ], - "can_expand": true + ] }, { "name": "RedditorsStream", @@ -76,8 +71,7 @@ "reference_start_line": 93, "reference_end_line": 104 } - ], - "can_expand": true + ] }, { "name": "InboxStream", @@ -89,8 +83,7 @@ "reference_start_line": 229, "reference_end_line": 247 } - ], - "can_expand": true + ] }, { "name": "SubredditContentStream", @@ -102,8 +95,7 @@ "reference_start_line": 124, "reference_end_line": 133 } - ], - "can_expand": false + ] } ], "components_relations": [ diff --git a/.codeboarding/Listing_Streaming.rst b/.codeboarding/Listing_Streaming.rst index ff41e468c..4f4e2b01d 100644 --- a/.codeboarding/Listing_Streaming.rst +++ b/.codeboarding/Listing_Streaming.rst @@ -106,3 +106,9 @@ Represents the `stream` method within the `Subreddits` class, providing access t **Related Classes/Methods**: * `Subreddits.stream:124-133 `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/.codeboarding/Low_Level_API_Connector.json b/.codeboarding/Low_Level_API_Connector.json index 6603b1a3e..67d70518b 100644 --- a/.codeboarding/Low_Level_API_Connector.json +++ b/.codeboarding/Low_Level_API_Connector.json @@ -11,8 +11,7 @@ "reference_start_line": 1, "reference_end_line": 1 } - ], - "can_expand": true + ] }, { "name": "Low-Level API Connector", @@ -24,8 +23,7 @@ "reference_start_line": 527, "reference_end_line": 546 } - ], - "can_expand": true + ] }, { "name": "Authentication Module", @@ -37,8 +35,7 @@ "reference_start_line": 1, "reference_end_line": 1 } - ], - "can_expand": true + ] }, { "name": "Data Models/Objects", @@ -56,8 +53,7 @@ "reference_start_line": 1, "reference_end_line": 1 } - ], - "can_expand": true + ] }, { "name": "Configuration Management", @@ -69,8 +65,7 @@ "reference_start_line": 1, "reference_end_line": 1 } - ], - "can_expand": true + ] } ], "components_relations": [ diff --git a/.codeboarding/Low_Level_API_Connector.rst b/.codeboarding/Low_Level_API_Connector.rst index 62dcdc029..8c303a1ba 100644 --- a/.codeboarding/Low_Level_API_Connector.rst +++ b/.codeboarding/Low_Level_API_Connector.rst @@ -84,3 +84,9 @@ Handles the loading, parsing, and management of configuration settings (e.g., cl **Related Classes/Methods**: * `praw.config `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/.codeboarding/Object_Transformer.json b/.codeboarding/Object_Transformer.json index f3bdc4050..d0d459b3b 100644 --- a/.codeboarding/Object_Transformer.json +++ b/.codeboarding/Object_Transformer.json @@ -11,8 +11,7 @@ "reference_start_line": 17, "reference_end_line": 263 } - ], - "can_expand": true + ] }, { "name": "Objector.objectify Method", @@ -24,8 +23,7 @@ "reference_start_line": 1, "reference_end_line": 1 } - ], - "can_expand": false + ] }, { "name": "Objector._objectify_dict Method", @@ -37,8 +35,7 @@ "reference_start_line": 1, "reference_end_line": 1 } - ], - "can_expand": true + ] }, { "name": "Objector.check_error Method", @@ -50,8 +47,7 @@ "reference_start_line": 1, "reference_end_line": 1 } - ], - "can_expand": false + ] }, { "name": "Objector.parse_error Method", @@ -63,8 +59,7 @@ "reference_start_line": 1, "reference_end_line": 1 } - ], - "can_expand": false + ] } ], "components_relations": [ diff --git a/.codeboarding/Object_Transformer.rst b/.codeboarding/Object_Transformer.rst index 0da8a3e3a..61a90b2dd 100644 --- a/.codeboarding/Object_Transformer.rst +++ b/.codeboarding/Object_Transformer.rst @@ -75,3 +75,9 @@ Extracts and formats detailed error messages from the raw API response, converti **Related Classes/Methods**: * `praw.objector.Objector:parse_error `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/.codeboarding/Reddit_Client.json b/.codeboarding/Reddit_Client.json index 574eeab46..65b561776 100644 --- a/.codeboarding/Reddit_Client.json +++ b/.codeboarding/Reddit_Client.json @@ -11,8 +11,7 @@ "reference_start_line": 57, "reference_end_line": 901 } - ], - "can_expand": true + ] }, { "name": "Authentication Manager", @@ -42,8 +41,7 @@ "reference_start_line": 0, "reference_end_line": 0 } - ], - "can_expand": false + ] }, { "name": "HTTP Request Dispatcher", @@ -67,8 +65,7 @@ "reference_start_line": 0, "reference_end_line": 0 } - ], - "can_expand": true + ] }, { "name": "Response Object Mapper", @@ -80,8 +77,7 @@ "reference_start_line": 0, "reference_end_line": 0 } - ], - "can_expand": true + ] }, { "name": "Resource Accessors", @@ -153,8 +149,7 @@ "reference_start_line": 0, "reference_end_line": 0 } - ], - "can_expand": true + ] }, { "name": "Rate Limiting Handler", @@ -166,8 +161,7 @@ "reference_start_line": 0, "reference_end_line": 0 } - ], - "can_expand": true + ] } ], "components_relations": [ diff --git a/.codeboarding/Reddit_Client.rst b/.codeboarding/Reddit_Client.rst index 2bffa1895..ecc44610d 100644 --- a/.codeboarding/Reddit_Client.rst +++ b/.codeboarding/Reddit_Client.rst @@ -104,3 +104,9 @@ Monitors and enforces Reddit API rate limits. It pauses requests when necessary **Related Classes/Methods**: * `praw.reddit.Reddit:_handle_rate_limit `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/.codeboarding/Reddit_Data_Models.json b/.codeboarding/Reddit_Data_Models.json index 72436d5b4..4d7f139b8 100644 --- a/.codeboarding/Reddit_Data_Models.json +++ b/.codeboarding/Reddit_Data_Models.json @@ -11,8 +11,7 @@ "reference_start_line": 1, "reference_end_line": 1 } - ], - "can_expand": true + ] }, { "name": "praw.models.reddit.submission", @@ -24,8 +23,7 @@ "reference_start_line": 1, "reference_end_line": 1 } - ], - "can_expand": true + ] }, { "name": "praw.models.reddit.comment", @@ -37,8 +35,7 @@ "reference_start_line": 1, "reference_end_line": 1 } - ], - "can_expand": false + ] }, { "name": "praw.models.reddit.redditor", @@ -50,8 +47,7 @@ "reference_start_line": 1, "reference_end_line": 1 } - ], - "can_expand": false + ] }, { "name": "praw.models.reddit.modmail", @@ -63,8 +59,7 @@ "reference_start_line": 1, "reference_end_line": 1 } - ], - "can_expand": true + ] }, { "name": "praw.models.reddit.live", @@ -76,8 +71,7 @@ "reference_start_line": 1, "reference_end_line": 1 } - ], - "can_expand": true + ] }, { "name": "praw.models.reddit.widgets", @@ -89,8 +83,7 @@ "reference_start_line": 1, "reference_end_line": 1 } - ], - "can_expand": false + ] }, { "name": "praw.models.reddit.collections", @@ -102,8 +95,7 @@ "reference_start_line": 1, "reference_end_line": 1 } - ], - "can_expand": false + ] } ], "components_relations": [ diff --git a/.codeboarding/Reddit_Data_Models.rst b/.codeboarding/Reddit_Data_Models.rst index d51b2750b..58a6cacea 100644 --- a/.codeboarding/Reddit_Data_Models.rst +++ b/.codeboarding/Reddit_Data_Models.rst @@ -100,3 +100,9 @@ Manages post collections within a subreddit, providing an interface for creating **Related Classes/Methods**: * `praw.models.reddit.collections `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/.codeboarding/codeboarding_version.json b/.codeboarding/codeboarding_version.json index 94c718b63..90076d33a 100644 --- a/.codeboarding/codeboarding_version.json +++ b/.codeboarding/codeboarding_version.json @@ -1,4 +1,4 @@ { - "commit_hash": "6b3fa897303d414ede32c3788db04b0fcd124e37", + "commit_hash": "56cf6101ad03c1cfcdfd5040b4f1007fbc05d0a9", "code_boarding_version": "0.1.0" } diff --git a/.codeboarding/overview.rst b/.codeboarding/overview.rst index e34b3e868..f0514e5a9 100644 --- a/.codeboarding/overview.rst +++ b/.codeboarding/overview.rst @@ -101,3 +101,9 @@ Provides mechanisms for efficiently retrieving and iterating over collections of **Related Classes/Methods**: * `praw.models.listing `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/docs/architecture_overview/Listing_Streaming.rst b/docs/architecture_overview/Listing_Streaming.rst index ff41e468c..4f4e2b01d 100644 --- a/docs/architecture_overview/Listing_Streaming.rst +++ b/docs/architecture_overview/Listing_Streaming.rst @@ -106,3 +106,9 @@ Represents the `stream` method within the `Subreddits` class, providing access t **Related Classes/Methods**: * `Subreddits.stream:124-133 `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/docs/architecture_overview/Low_Level_API_Connector.rst b/docs/architecture_overview/Low_Level_API_Connector.rst index 62dcdc029..8c303a1ba 100644 --- a/docs/architecture_overview/Low_Level_API_Connector.rst +++ b/docs/architecture_overview/Low_Level_API_Connector.rst @@ -84,3 +84,9 @@ Handles the loading, parsing, and management of configuration settings (e.g., cl **Related Classes/Methods**: * `praw.config `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/docs/architecture_overview/Object_Transformer.rst b/docs/architecture_overview/Object_Transformer.rst index 0da8a3e3a..61a90b2dd 100644 --- a/docs/architecture_overview/Object_Transformer.rst +++ b/docs/architecture_overview/Object_Transformer.rst @@ -75,3 +75,9 @@ Extracts and formats detailed error messages from the raw API response, converti **Related Classes/Methods**: * `praw.objector.Objector:parse_error `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/docs/architecture_overview/Reddit_Client.rst b/docs/architecture_overview/Reddit_Client.rst index 2bffa1895..ecc44610d 100644 --- a/docs/architecture_overview/Reddit_Client.rst +++ b/docs/architecture_overview/Reddit_Client.rst @@ -104,3 +104,9 @@ Monitors and enforces Reddit API rate limits. It pauses requests when necessary **Related Classes/Methods**: * `praw.reddit.Reddit:_handle_rate_limit `_ + + +FAQ +--- + +`See the FAQ `_ diff --git a/docs/architecture_overview/overview.rst b/docs/architecture_overview/overview.rst index e34b3e868..f0514e5a9 100644 --- a/docs/architecture_overview/overview.rst +++ b/docs/architecture_overview/overview.rst @@ -101,3 +101,9 @@ Provides mechanisms for efficiently retrieving and iterating over collections of **Related Classes/Methods**: * `praw.models.listing `_ + + +FAQ +--- + +`See the FAQ `_ From acb8067d310918c73d5b7e1c7d8aee73c3d2a3c3 Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Sun, 7 Sep 2025 20:21:35 +0000 Subject: [PATCH 16/23] docs: update codeboarding documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 📚 Documentation Update This commit contains updated documentation files fetched from the CodeBoarding service. ### 📊 Summary - Documentation files created/updated: 6 - JSON files created/updated: 7 - Documentation directory: .codeboarding/ - JSON directory: .codeboarding/ - Output format: .rst - Repository analyzed: https://github.com/CodeBoarding/praw - Source branch: main - Target branch: main 🤖 This commit was automatically generated by the CodeBoarding documentation update workflow. --- .codeboarding/codeboarding_version.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.codeboarding/codeboarding_version.json b/.codeboarding/codeboarding_version.json index 90076d33a..7ccb64424 100644 --- a/.codeboarding/codeboarding_version.json +++ b/.codeboarding/codeboarding_version.json @@ -1,4 +1,4 @@ { - "commit_hash": "56cf6101ad03c1cfcdfd5040b4f1007fbc05d0a9", + "commit_hash": "243a716baa5f6ac1bcc5be3b6cf546c27d166d90", "code_boarding_version": "0.1.0" } From de461083353c3e41a64f14ec289d02396f18db39 Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Sun, 14 Sep 2025 20:25:35 +0000 Subject: [PATCH 17/23] docs: update codeboarding documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 📚 Documentation Update This commit contains updated documentation files fetched from the CodeBoarding service. ### 📊 Summary - Documentation files created/updated: 7 - JSON files created/updated: 8 - Documentation directory: .codeboarding/ - JSON directory: .codeboarding/ - Output format: .rst - Repository analyzed: https://github.com/CodeBoarding/praw - Source branch: main - Target branch: main 🤖 This commit was automatically generated by the CodeBoarding documentation update workflow. --- .codeboarding/Configuration_Manager.json | 88 ++++++++++++++ .codeboarding/Configuration_Manager.rst | 67 +++++++++++ .codeboarding/Listing_Streaming.rst | 6 - .codeboarding/Low_Level_API_Connector.rst | 6 - .codeboarding/Object_Transformer.rst | 6 - .codeboarding/Reddit_Client.rst | 6 - .codeboarding/Reddit_Data_Models.rst | 6 - .codeboarding/analysis.json | 107 +++++++++++++++++- .codeboarding/codeboarding_version.json | 4 +- .codeboarding/overview.rst | 11 +- .../Configuration_Manager.rst | 67 +++++++++++ .../Listing_Streaming.rst | 6 - .../Low_Level_API_Connector.rst | 6 - .../Object_Transformer.rst | 6 - docs/architecture_overview/Reddit_Client.rst | 6 - .../Reddit_Data_Models.rst | 6 - docs/architecture_overview/overview.rst | 11 +- 17 files changed, 346 insertions(+), 69 deletions(-) create mode 100644 .codeboarding/Configuration_Manager.json create mode 100644 .codeboarding/Configuration_Manager.rst create mode 100644 docs/architecture_overview/Configuration_Manager.rst diff --git a/.codeboarding/Configuration_Manager.json b/.codeboarding/Configuration_Manager.json new file mode 100644 index 000000000..de15a2ff9 --- /dev/null +++ b/.codeboarding/Configuration_Manager.json @@ -0,0 +1,88 @@ +{ + "description": "The PRAW library's core architecture is built around three central components: the `Configuration Manager`, the `High-Level API Interface`, and the `Authentication Module`. The `Configuration Manager` acts as the foundational layer, centralizing and providing all necessary configuration settings, including API credentials and user agent strings, to other components. The `High-Level API Interface` serves as the primary entry point for users, orchestrating API requests and relying on the `Configuration Manager` for initial setup. Crucially, the `Authentication Module` handles secure interactions with the Reddit API by managing OAuth2 flows, acquiring and refreshing access tokens, and utilizing credentials supplied by the `Configuration Manager`. This modular design ensures a clear separation of concerns, promoting maintainability and robust interaction with the Reddit API.", + "components": [ + { + "name": "Configuration Manager", + "description": "This is the core component responsible for loading, parsing, and validating configuration settings for PRAW. It sources settings from various locations, including `praw.ini` files and environment variables, and provides a unified, structured interface for other parts of the library to access critical values such as API credentials, user agent strings, and other operational parameters. It also handles the application of default values when specific settings are not provided. This component is fundamental as it centralizes all configurable parameters, ensuring consistent and correct behavior across the API client.", + "referenced_source_code": [ + { + "qualified_name": "praw.config.Config", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/config.py", + "reference_start_line": null, + "reference_end_line": null + } + ], + "assigned_files": [ + "/home/ubuntu/CodeBoarding/repo/praw/praw/config.py" + ], + "can_expand": true + }, + { + "name": "High-Level API Interface", + "description": "This component represents the primary entry point for users to interact with the Reddit API. It encapsulates the overall client functionality and orchestrates API requests. It relies on the `Configuration Manager` to initialize itself with necessary settings like the user agent and other API-specific parameters, ensuring the client is properly configured before making any calls.", + "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 + } + ], + "assigned_files": [], + "can_expand": true + }, + { + "name": "Authentication Module", + "description": "This conceptual component is responsible for handling the authentication process with the Reddit API, typically involving OAuth2 flows. It manages the acquisition, storage, and refreshing of access tokens and utilizes credentials (e.g., `client_id`, `client_secret`) provided by the `Configuration Manager` to establish authenticated sessions. This module is critical for securing API interactions.", + "referenced_source_code": [ + { + "qualified_name": "praw.models.auth.Auth", + "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/auth.py", + "reference_start_line": null, + "reference_end_line": null + } + ], + "assigned_files": [], + "can_expand": true + }, + { + "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": "provides configuration to", + "src_name": "Configuration Manager", + "dst_name": "High-Level API Interface" + }, + { + "relation": "provides configuration to", + "src_name": "Configuration Manager", + "dst_name": "Authentication Module" + }, + { + "relation": "consumes configuration from", + "src_name": "High-Level API Interface", + "dst_name": "Configuration Manager" + }, + { + "relation": "utilizes", + "src_name": "High-Level API Interface", + "dst_name": "Authentication Module" + }, + { + "relation": "consumes credentials from", + "src_name": "Authentication Module", + "dst_name": "Configuration Manager" + }, + { + "relation": "provides authenticated sessions/tokens to", + "src_name": "Authentication Module", + "dst_name": "High-Level API Interface" + } + ] +} diff --git a/.codeboarding/Configuration_Manager.rst b/.codeboarding/Configuration_Manager.rst new file mode 100644 index 000000000..49a06b7d4 --- /dev/null +++ b/.codeboarding/Configuration_Manager.rst @@ -0,0 +1,67 @@ +Configuration Manager +===================== + +.. mermaid:: + + graph LR + Configuration_Manager["Configuration Manager"] + High_Level_API_Interface["High-Level API Interface"] + Authentication_Module["Authentication Module"] + Unclassified["Unclassified"] + Configuration_Manager -- "provides configuration to" --> High_Level_API_Interface + Configuration_Manager -- "provides configuration to" --> Authentication_Module + High_Level_API_Interface -- "consumes configuration from" --> Configuration_Manager + High_Level_API_Interface -- "utilizes" --> Authentication_Module + Authentication_Module -- "consumes credentials from" --> Configuration_Manager + Authentication_Module -- "provides authenticated sessions/tokens to" --> High_Level_API_Interface + 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 built around three central components: the `Configuration Manager`, the `High-Level API Interface`, and the `Authentication Module`. The `Configuration Manager` acts as the foundational layer, centralizing and providing all necessary configuration settings, including API credentials and user agent strings, to other components. The `High-Level API Interface` serves as the primary entry point for users, orchestrating API requests and relying on the `Configuration Manager` for initial setup. Crucially, the `Authentication Module` handles secure interactions with the Reddit API by managing OAuth2 flows, acquiring and refreshing access tokens, and utilizing credentials supplied by the `Configuration Manager`. This modular design ensures a clear separation of concerns, promoting maintainability and robust interaction with the Reddit API. + +Configuration Manager +^^^^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +This is the core component responsible for loading, parsing, and validating configuration settings for PRAW. It sources settings from various locations, including `praw.ini` files and environment variables, and provides a unified, structured interface for other parts of the library to access critical values such as API credentials, user agent strings, and other operational parameters. It also handles the application of default values when specific settings are not provided. This component is fundamental as it centralizes all configurable parameters, ensuring consistent and correct behavior across the API client. + +**Related Classes/Methods**: + +* `praw.config.Config `_ + +High-Level API Interface +^^^^^^^^^^^^^^^^^^^^^^^^ + +This component represents the primary entry point for users to interact with the Reddit API. It encapsulates the overall client functionality and orchestrates API requests. It relies on the `Configuration Manager` to initialize itself with necessary settings like the user agent and other API-specific parameters, ensuring the client is properly configured before making any calls. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit:57-901 `_ + +Authentication Module +^^^^^^^^^^^^^^^^^^^^^ + +This conceptual component is responsible for handling the authentication process with the Reddit API, typically involving OAuth2 flows. It manages the acquisition, storage, and refreshing of access tokens and utilizes credentials (e.g., `client_id`, `client_secret`) provided by the `Configuration Manager` to establish authenticated sessions. This module is critical for securing API interactions. + +**Related Classes/Methods**: + +* `praw.models.auth.Auth `_ + +Unclassified +^^^^^^^^^^^^ + +Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies) + +**Related Classes/Methods**: *None* diff --git a/.codeboarding/Listing_Streaming.rst b/.codeboarding/Listing_Streaming.rst index 4f4e2b01d..ff41e468c 100644 --- a/.codeboarding/Listing_Streaming.rst +++ b/.codeboarding/Listing_Streaming.rst @@ -106,9 +106,3 @@ Represents the `stream` method within the `Subreddits` class, providing access t **Related Classes/Methods**: * `Subreddits.stream:124-133 `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/.codeboarding/Low_Level_API_Connector.rst b/.codeboarding/Low_Level_API_Connector.rst index 8c303a1ba..62dcdc029 100644 --- a/.codeboarding/Low_Level_API_Connector.rst +++ b/.codeboarding/Low_Level_API_Connector.rst @@ -84,9 +84,3 @@ Handles the loading, parsing, and management of configuration settings (e.g., cl **Related Classes/Methods**: * `praw.config `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/.codeboarding/Object_Transformer.rst b/.codeboarding/Object_Transformer.rst index 61a90b2dd..0da8a3e3a 100644 --- a/.codeboarding/Object_Transformer.rst +++ b/.codeboarding/Object_Transformer.rst @@ -75,9 +75,3 @@ Extracts and formats detailed error messages from the raw API response, converti **Related Classes/Methods**: * `praw.objector.Objector:parse_error `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/.codeboarding/Reddit_Client.rst b/.codeboarding/Reddit_Client.rst index ecc44610d..2bffa1895 100644 --- a/.codeboarding/Reddit_Client.rst +++ b/.codeboarding/Reddit_Client.rst @@ -104,9 +104,3 @@ Monitors and enforces Reddit API rate limits. It pauses requests when necessary **Related Classes/Methods**: * `praw.reddit.Reddit:_handle_rate_limit `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/.codeboarding/Reddit_Data_Models.rst b/.codeboarding/Reddit_Data_Models.rst index 58a6cacea..d51b2750b 100644 --- a/.codeboarding/Reddit_Data_Models.rst +++ b/.codeboarding/Reddit_Data_Models.rst @@ -100,9 +100,3 @@ Manages post collections within a subreddit, providing an interface for creating **Related Classes/Methods**: * `praw.models.reddit.collections `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/.codeboarding/analysis.json b/.codeboarding/analysis.json index 71209b3a9..9812af3a6 100644 --- a/.codeboarding/analysis.json +++ b/.codeboarding/analysis.json @@ -12,6 +12,11 @@ "reference_end_line": 1 } ], + "assigned_files": [ + "/home/ubuntu/CodeBoarding/repo/praw/praw/__init__.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/endpoints.py" + ], "can_expand": true }, { @@ -25,7 +30,10 @@ "reference_end_line": 1 } ], - "can_expand": false + "assigned_files": [ + "/home/ubuntu/CodeBoarding/repo/praw/praw/config.py" + ], + "can_expand": true }, { "name": "Low-Level API Connector", @@ -38,6 +46,7 @@ "reference_end_line": 546 } ], + "assigned_files": [], "can_expand": true }, { @@ -51,6 +60,9 @@ "reference_end_line": 1 } ], + "assigned_files": [ + "/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py" + ], "can_expand": true }, { @@ -64,6 +76,57 @@ "reference_end_line": 1 } ], + "assigned_files": [ + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/__init__.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/mod_note.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/base.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/util.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/front.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/preferences.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/redditors.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/mod_action.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/user.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/comment_forest.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/mod_notes.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/trophy.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/helpers.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/inbox.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/subreddits.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/stylesheet.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/auth.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/__init__.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/submission.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/widgets.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/base.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/subreddit.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/removal_reasons.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/draft.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/user_subreddit.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/rules.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/poll.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/redditor.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/modmail.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/comment.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/collections.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/emoji.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/more.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/multi.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/live.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/message.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/inline_media.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/wikipage.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/__init__.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/inboxtoggleable.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/inboxable.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/savable.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/reportable.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/fullname.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/messageable.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/modnote.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/replyable.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/editable.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/votable.py" + ], "can_expand": true }, { @@ -77,7 +140,49 @@ "reference_end_line": 1 } ], + "assigned_files": [ + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/list/moderated.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/list/__init__.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/list/base.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/list/draft.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/list/redditor.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/list/trophy.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/__init__.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/domain.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/listing.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/mixins/__init__.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/mixins/submission.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/mixins/base.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/mixins/subreddit.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/mixins/redditor.py", + "/home/ubuntu/CodeBoarding/repo/praw/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": [ + "/home/ubuntu/CodeBoarding/repo/praw/pre_push.py", + "/home/ubuntu/CodeBoarding/repo/praw/tools/__init__.py", + "/home/ubuntu/CodeBoarding/repo/praw/tools/set_version.py", + "/home/ubuntu/CodeBoarding/repo/praw/tools/set_active_docs.py", + "/home/ubuntu/CodeBoarding/repo/praw/tools/static_word_checks.py", + "/home/ubuntu/CodeBoarding/repo/praw/tools/bump_version.py", + "/home/ubuntu/CodeBoarding/repo/praw/tools/check_documentation.py", + "/home/ubuntu/CodeBoarding/repo/praw/tools/extract_log_entry.py", + "/home/ubuntu/CodeBoarding/repo/praw/docs/conf.py", + "/home/ubuntu/CodeBoarding/repo/praw/docs/examples/obtain_refresh_token.py", + "/home/ubuntu/CodeBoarding/repo/praw/docs/examples/lmgtfy_bot.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/const.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/util/__init__.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/util/cache.py", + "/home/ubuntu/CodeBoarding/repo/praw/praw/util/snake.py" + ], + "can_expand": false } ], "components_relations": [ diff --git a/.codeboarding/codeboarding_version.json b/.codeboarding/codeboarding_version.json index 7ccb64424..726e1074c 100644 --- a/.codeboarding/codeboarding_version.json +++ b/.codeboarding/codeboarding_version.json @@ -1,4 +1,4 @@ { - "commit_hash": "243a716baa5f6ac1bcc5be3b6cf546c27d166d90", - "code_boarding_version": "0.1.0" + "commit_hash": "acb8067d310918c73d5b7e1c7d8aee73c3d2a3c3", + "code_boarding_version": "0.2.0" } diff --git a/.codeboarding/overview.rst b/.codeboarding/overview.rst index f0514e5a9..20b5b7097 100644 --- a/.codeboarding/overview.rst +++ b/.codeboarding/overview.rst @@ -10,6 +10,7 @@ Overview Object_Transformer["Object Transformer"] Reddit_Data_Models["Reddit Data Models"] Listing_Streaming["Listing & Streaming"] + 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 @@ -19,6 +20,7 @@ Overview 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" @@ -52,6 +54,8 @@ The primary interface for interacting with the Reddit API, managing authenticati Configuration Manager ^^^^^^^^^^^^^^^^^^^^^ +:ref:`Expand ` + Manages loading and accessing PRAW's configuration settings. **Related Classes/Methods**: @@ -102,8 +106,9 @@ Provides mechanisms for efficiently retrieving and iterating over collections of * `praw.models.listing `_ +Unclassified +^^^^^^^^^^^^ -FAQ ---- +Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies) -`See the FAQ `_ +**Related Classes/Methods**: *None* diff --git a/docs/architecture_overview/Configuration_Manager.rst b/docs/architecture_overview/Configuration_Manager.rst new file mode 100644 index 000000000..49a06b7d4 --- /dev/null +++ b/docs/architecture_overview/Configuration_Manager.rst @@ -0,0 +1,67 @@ +Configuration Manager +===================== + +.. mermaid:: + + graph LR + Configuration_Manager["Configuration Manager"] + High_Level_API_Interface["High-Level API Interface"] + Authentication_Module["Authentication Module"] + Unclassified["Unclassified"] + Configuration_Manager -- "provides configuration to" --> High_Level_API_Interface + Configuration_Manager -- "provides configuration to" --> Authentication_Module + High_Level_API_Interface -- "consumes configuration from" --> Configuration_Manager + High_Level_API_Interface -- "utilizes" --> Authentication_Module + Authentication_Module -- "consumes credentials from" --> Configuration_Manager + Authentication_Module -- "provides authenticated sessions/tokens to" --> High_Level_API_Interface + 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 built around three central components: the `Configuration Manager`, the `High-Level API Interface`, and the `Authentication Module`. The `Configuration Manager` acts as the foundational layer, centralizing and providing all necessary configuration settings, including API credentials and user agent strings, to other components. The `High-Level API Interface` serves as the primary entry point for users, orchestrating API requests and relying on the `Configuration Manager` for initial setup. Crucially, the `Authentication Module` handles secure interactions with the Reddit API by managing OAuth2 flows, acquiring and refreshing access tokens, and utilizing credentials supplied by the `Configuration Manager`. This modular design ensures a clear separation of concerns, promoting maintainability and robust interaction with the Reddit API. + +Configuration Manager +^^^^^^^^^^^^^^^^^^^^^ + +:ref:`Expand ` + +This is the core component responsible for loading, parsing, and validating configuration settings for PRAW. It sources settings from various locations, including `praw.ini` files and environment variables, and provides a unified, structured interface for other parts of the library to access critical values such as API credentials, user agent strings, and other operational parameters. It also handles the application of default values when specific settings are not provided. This component is fundamental as it centralizes all configurable parameters, ensuring consistent and correct behavior across the API client. + +**Related Classes/Methods**: + +* `praw.config.Config `_ + +High-Level API Interface +^^^^^^^^^^^^^^^^^^^^^^^^ + +This component represents the primary entry point for users to interact with the Reddit API. It encapsulates the overall client functionality and orchestrates API requests. It relies on the `Configuration Manager` to initialize itself with necessary settings like the user agent and other API-specific parameters, ensuring the client is properly configured before making any calls. + +**Related Classes/Methods**: + +* `praw.reddit.Reddit:57-901 `_ + +Authentication Module +^^^^^^^^^^^^^^^^^^^^^ + +This conceptual component is responsible for handling the authentication process with the Reddit API, typically involving OAuth2 flows. It manages the acquisition, storage, and refreshing of access tokens and utilizes credentials (e.g., `client_id`, `client_secret`) provided by the `Configuration Manager` to establish authenticated sessions. This module is critical for securing API interactions. + +**Related Classes/Methods**: + +* `praw.models.auth.Auth `_ + +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 index 4f4e2b01d..ff41e468c 100644 --- a/docs/architecture_overview/Listing_Streaming.rst +++ b/docs/architecture_overview/Listing_Streaming.rst @@ -106,9 +106,3 @@ Represents the `stream` method within the `Subreddits` class, providing access t **Related Classes/Methods**: * `Subreddits.stream:124-133 `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/docs/architecture_overview/Low_Level_API_Connector.rst b/docs/architecture_overview/Low_Level_API_Connector.rst index 8c303a1ba..62dcdc029 100644 --- a/docs/architecture_overview/Low_Level_API_Connector.rst +++ b/docs/architecture_overview/Low_Level_API_Connector.rst @@ -84,9 +84,3 @@ Handles the loading, parsing, and management of configuration settings (e.g., cl **Related Classes/Methods**: * `praw.config `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/docs/architecture_overview/Object_Transformer.rst b/docs/architecture_overview/Object_Transformer.rst index 61a90b2dd..0da8a3e3a 100644 --- a/docs/architecture_overview/Object_Transformer.rst +++ b/docs/architecture_overview/Object_Transformer.rst @@ -75,9 +75,3 @@ Extracts and formats detailed error messages from the raw API response, converti **Related Classes/Methods**: * `praw.objector.Objector:parse_error `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/docs/architecture_overview/Reddit_Client.rst b/docs/architecture_overview/Reddit_Client.rst index ecc44610d..2bffa1895 100644 --- a/docs/architecture_overview/Reddit_Client.rst +++ b/docs/architecture_overview/Reddit_Client.rst @@ -104,9 +104,3 @@ Monitors and enforces Reddit API rate limits. It pauses requests when necessary **Related Classes/Methods**: * `praw.reddit.Reddit:_handle_rate_limit `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/docs/architecture_overview/Reddit_Data_Models.rst b/docs/architecture_overview/Reddit_Data_Models.rst index 58a6cacea..d51b2750b 100644 --- a/docs/architecture_overview/Reddit_Data_Models.rst +++ b/docs/architecture_overview/Reddit_Data_Models.rst @@ -100,9 +100,3 @@ Manages post collections within a subreddit, providing an interface for creating **Related Classes/Methods**: * `praw.models.reddit.collections `_ - - -FAQ ---- - -`See the FAQ `_ diff --git a/docs/architecture_overview/overview.rst b/docs/architecture_overview/overview.rst index f0514e5a9..20b5b7097 100644 --- a/docs/architecture_overview/overview.rst +++ b/docs/architecture_overview/overview.rst @@ -10,6 +10,7 @@ Overview Object_Transformer["Object Transformer"] Reddit_Data_Models["Reddit Data Models"] Listing_Streaming["Listing & Streaming"] + 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 @@ -19,6 +20,7 @@ Overview 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" @@ -52,6 +54,8 @@ The primary interface for interacting with the Reddit API, managing authenticati Configuration Manager ^^^^^^^^^^^^^^^^^^^^^ +:ref:`Expand ` + Manages loading and accessing PRAW's configuration settings. **Related Classes/Methods**: @@ -102,8 +106,9 @@ Provides mechanisms for efficiently retrieving and iterating over collections of * `praw.models.listing `_ +Unclassified +^^^^^^^^^^^^ -FAQ ---- +Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies) -`See the FAQ `_ +**Related Classes/Methods**: *None* From 090164fb6f365f6fd83ea6ad67fe82d29e1df408 Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Sun, 21 Sep 2025 20:23:11 +0000 Subject: [PATCH 18/23] docs: update codeboarding documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 📚 Documentation Update This commit contains updated documentation files fetched from the CodeBoarding service. ### 📊 Summary - Documentation files created/updated: 6 - JSON files created/updated: 7 - Documentation directory: .codeboarding/ - JSON directory: .codeboarding/ - Output format: .rst - Repository analyzed: https://github.com/CodeBoarding/praw - Source branch: main - Target branch: main 🤖 This commit was automatically generated by the CodeBoarding documentation update workflow. --- .codeboarding/Configuration_Manager.json | 88 ----------- .codeboarding/Configuration_Manager.rst | 67 --------- .codeboarding/analysis.json | 181 ++++++++++++----------- .codeboarding/codeboarding_version.json | 2 +- .codeboarding/overview.rst | 11 +- docs/architecture_overview/overview.rst | 11 +- 6 files changed, 111 insertions(+), 249 deletions(-) delete mode 100644 .codeboarding/Configuration_Manager.json delete mode 100644 .codeboarding/Configuration_Manager.rst diff --git a/.codeboarding/Configuration_Manager.json b/.codeboarding/Configuration_Manager.json deleted file mode 100644 index de15a2ff9..000000000 --- a/.codeboarding/Configuration_Manager.json +++ /dev/null @@ -1,88 +0,0 @@ -{ - "description": "The PRAW library's core architecture is built around three central components: the `Configuration Manager`, the `High-Level API Interface`, and the `Authentication Module`. The `Configuration Manager` acts as the foundational layer, centralizing and providing all necessary configuration settings, including API credentials and user agent strings, to other components. The `High-Level API Interface` serves as the primary entry point for users, orchestrating API requests and relying on the `Configuration Manager` for initial setup. Crucially, the `Authentication Module` handles secure interactions with the Reddit API by managing OAuth2 flows, acquiring and refreshing access tokens, and utilizing credentials supplied by the `Configuration Manager`. This modular design ensures a clear separation of concerns, promoting maintainability and robust interaction with the Reddit API.", - "components": [ - { - "name": "Configuration Manager", - "description": "This is the core component responsible for loading, parsing, and validating configuration settings for PRAW. It sources settings from various locations, including `praw.ini` files and environment variables, and provides a unified, structured interface for other parts of the library to access critical values such as API credentials, user agent strings, and other operational parameters. It also handles the application of default values when specific settings are not provided. This component is fundamental as it centralizes all configurable parameters, ensuring consistent and correct behavior across the API client.", - "referenced_source_code": [ - { - "qualified_name": "praw.config.Config", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/config.py", - "reference_start_line": null, - "reference_end_line": null - } - ], - "assigned_files": [ - "/home/ubuntu/CodeBoarding/repo/praw/praw/config.py" - ], - "can_expand": true - }, - { - "name": "High-Level API Interface", - "description": "This component represents the primary entry point for users to interact with the Reddit API. It encapsulates the overall client functionality and orchestrates API requests. It relies on the `Configuration Manager` to initialize itself with necessary settings like the user agent and other API-specific parameters, ensuring the client is properly configured before making any calls.", - "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 - } - ], - "assigned_files": [], - "can_expand": true - }, - { - "name": "Authentication Module", - "description": "This conceptual component is responsible for handling the authentication process with the Reddit API, typically involving OAuth2 flows. It manages the acquisition, storage, and refreshing of access tokens and utilizes credentials (e.g., `client_id`, `client_secret`) provided by the `Configuration Manager` to establish authenticated sessions. This module is critical for securing API interactions.", - "referenced_source_code": [ - { - "qualified_name": "praw.models.auth.Auth", - "reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/models/auth.py", - "reference_start_line": null, - "reference_end_line": null - } - ], - "assigned_files": [], - "can_expand": true - }, - { - "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": "provides configuration to", - "src_name": "Configuration Manager", - "dst_name": "High-Level API Interface" - }, - { - "relation": "provides configuration to", - "src_name": "Configuration Manager", - "dst_name": "Authentication Module" - }, - { - "relation": "consumes configuration from", - "src_name": "High-Level API Interface", - "dst_name": "Configuration Manager" - }, - { - "relation": "utilizes", - "src_name": "High-Level API Interface", - "dst_name": "Authentication Module" - }, - { - "relation": "consumes credentials from", - "src_name": "Authentication Module", - "dst_name": "Configuration Manager" - }, - { - "relation": "provides authenticated sessions/tokens to", - "src_name": "Authentication Module", - "dst_name": "High-Level API Interface" - } - ] -} diff --git a/.codeboarding/Configuration_Manager.rst b/.codeboarding/Configuration_Manager.rst deleted file mode 100644 index 49a06b7d4..000000000 --- a/.codeboarding/Configuration_Manager.rst +++ /dev/null @@ -1,67 +0,0 @@ -Configuration Manager -===================== - -.. mermaid:: - - graph LR - Configuration_Manager["Configuration Manager"] - High_Level_API_Interface["High-Level API Interface"] - Authentication_Module["Authentication Module"] - Unclassified["Unclassified"] - Configuration_Manager -- "provides configuration to" --> High_Level_API_Interface - Configuration_Manager -- "provides configuration to" --> Authentication_Module - High_Level_API_Interface -- "consumes configuration from" --> Configuration_Manager - High_Level_API_Interface -- "utilizes" --> Authentication_Module - Authentication_Module -- "consumes credentials from" --> Configuration_Manager - Authentication_Module -- "provides authenticated sessions/tokens to" --> High_Level_API_Interface - 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 built around three central components: the `Configuration Manager`, the `High-Level API Interface`, and the `Authentication Module`. The `Configuration Manager` acts as the foundational layer, centralizing and providing all necessary configuration settings, including API credentials and user agent strings, to other components. The `High-Level API Interface` serves as the primary entry point for users, orchestrating API requests and relying on the `Configuration Manager` for initial setup. Crucially, the `Authentication Module` handles secure interactions with the Reddit API by managing OAuth2 flows, acquiring and refreshing access tokens, and utilizing credentials supplied by the `Configuration Manager`. This modular design ensures a clear separation of concerns, promoting maintainability and robust interaction with the Reddit API. - -Configuration Manager -^^^^^^^^^^^^^^^^^^^^^ - -:ref:`Expand ` - -This is the core component responsible for loading, parsing, and validating configuration settings for PRAW. It sources settings from various locations, including `praw.ini` files and environment variables, and provides a unified, structured interface for other parts of the library to access critical values such as API credentials, user agent strings, and other operational parameters. It also handles the application of default values when specific settings are not provided. This component is fundamental as it centralizes all configurable parameters, ensuring consistent and correct behavior across the API client. - -**Related Classes/Methods**: - -* `praw.config.Config `_ - -High-Level API Interface -^^^^^^^^^^^^^^^^^^^^^^^^ - -This component represents the primary entry point for users to interact with the Reddit API. It encapsulates the overall client functionality and orchestrates API requests. It relies on the `Configuration Manager` to initialize itself with necessary settings like the user agent and other API-specific parameters, ensuring the client is properly configured before making any calls. - -**Related Classes/Methods**: - -* `praw.reddit.Reddit:57-901 `_ - -Authentication Module -^^^^^^^^^^^^^^^^^^^^^ - -This conceptual component is responsible for handling the authentication process with the Reddit API, typically involving OAuth2 flows. It manages the acquisition, storage, and refreshing of access tokens and utilizes credentials (e.g., `client_id`, `client_secret`) provided by the `Configuration Manager` to establish authenticated sessions. This module is critical for securing API interactions. - -**Related Classes/Methods**: - -* `praw.models.auth.Auth `_ - -Unclassified -^^^^^^^^^^^^ - -Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies) - -**Related Classes/Methods**: *None* diff --git a/.codeboarding/analysis.json b/.codeboarding/analysis.json index 9812af3a6..c0c568e45 100644 --- a/.codeboarding/analysis.json +++ b/.codeboarding/analysis.json @@ -13,9 +13,8 @@ } ], "assigned_files": [ - "/home/ubuntu/CodeBoarding/repo/praw/praw/__init__.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/endpoints.py" + "praw/reddit.py", + "praw/endpoints.py" ], "can_expand": true }, @@ -31,9 +30,9 @@ } ], "assigned_files": [ - "/home/ubuntu/CodeBoarding/repo/praw/praw/config.py" + "praw/config.py" ], - "can_expand": true + "can_expand": false }, { "name": "Low-Level API Connector", @@ -61,7 +60,7 @@ } ], "assigned_files": [ - "/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py" + "praw/objector.py" ], "can_expand": true }, @@ -77,55 +76,55 @@ } ], "assigned_files": [ - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/__init__.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/mod_note.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/base.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/util.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/front.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/preferences.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/redditors.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/mod_action.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/user.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/comment_forest.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/mod_notes.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/trophy.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/helpers.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/inbox.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/subreddits.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/stylesheet.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/auth.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/__init__.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/submission.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/widgets.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/base.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/subreddit.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/removal_reasons.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/draft.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/user_subreddit.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/rules.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/poll.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/redditor.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/modmail.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/comment.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/collections.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/emoji.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/more.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/multi.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/live.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/message.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/inline_media.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/wikipage.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/__init__.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/inboxtoggleable.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/inboxable.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/savable.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/reportable.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/fullname.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/messageable.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/modnote.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/replyable.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/editable.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/reddit/mixins/votable.py" + "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 }, @@ -141,22 +140,22 @@ } ], "assigned_files": [ - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/list/moderated.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/list/__init__.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/list/base.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/list/draft.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/list/redditor.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/list/trophy.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/__init__.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/domain.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/listing.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/mixins/__init__.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/mixins/submission.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/mixins/base.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/mixins/subreddit.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/mixins/redditor.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/mixins/rising.py" + "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 }, @@ -165,24 +164,32 @@ "description": "Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies)", "referenced_source_code": [], "assigned_files": [ - "/home/ubuntu/CodeBoarding/repo/praw/pre_push.py", - "/home/ubuntu/CodeBoarding/repo/praw/tools/__init__.py", - "/home/ubuntu/CodeBoarding/repo/praw/tools/set_version.py", - "/home/ubuntu/CodeBoarding/repo/praw/tools/set_active_docs.py", - "/home/ubuntu/CodeBoarding/repo/praw/tools/static_word_checks.py", - "/home/ubuntu/CodeBoarding/repo/praw/tools/bump_version.py", - "/home/ubuntu/CodeBoarding/repo/praw/tools/check_documentation.py", - "/home/ubuntu/CodeBoarding/repo/praw/tools/extract_log_entry.py", - "/home/ubuntu/CodeBoarding/repo/praw/docs/conf.py", - "/home/ubuntu/CodeBoarding/repo/praw/docs/examples/obtain_refresh_token.py", - "/home/ubuntu/CodeBoarding/repo/praw/docs/examples/lmgtfy_bot.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/const.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/util/__init__.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/util/cache.py", - "/home/ubuntu/CodeBoarding/repo/praw/praw/util/snake.py" + "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/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 } ], "components_relations": [ diff --git a/.codeboarding/codeboarding_version.json b/.codeboarding/codeboarding_version.json index 726e1074c..163ee246e 100644 --- a/.codeboarding/codeboarding_version.json +++ b/.codeboarding/codeboarding_version.json @@ -1,4 +1,4 @@ { - "commit_hash": "acb8067d310918c73d5b7e1c7d8aee73c3d2a3c3", + "commit_hash": "de461083353c3e41a64f14ec289d02396f18db39", "code_boarding_version": "0.2.0" } diff --git a/.codeboarding/overview.rst b/.codeboarding/overview.rst index 20b5b7097..1685abdc7 100644 --- a/.codeboarding/overview.rst +++ b/.codeboarding/overview.rst @@ -11,6 +11,7 @@ Overview Reddit_Data_Models["Reddit Data Models"] Listing_Streaming["Listing & Streaming"] 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 @@ -20,7 +21,6 @@ Overview 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" @@ -54,8 +54,6 @@ The primary interface for interacting with the Reddit API, managing authenticati Configuration Manager ^^^^^^^^^^^^^^^^^^^^^ -:ref:`Expand ` - Manages loading and accessing PRAW's configuration settings. **Related Classes/Methods**: @@ -112,3 +110,10 @@ 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/architecture_overview/overview.rst b/docs/architecture_overview/overview.rst index 20b5b7097..1685abdc7 100644 --- a/docs/architecture_overview/overview.rst +++ b/docs/architecture_overview/overview.rst @@ -11,6 +11,7 @@ Overview Reddit_Data_Models["Reddit Data Models"] Listing_Streaming["Listing & Streaming"] 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 @@ -20,7 +21,6 @@ Overview 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" @@ -54,8 +54,6 @@ The primary interface for interacting with the Reddit API, managing authenticati Configuration Manager ^^^^^^^^^^^^^^^^^^^^^ -:ref:`Expand ` - Manages loading and accessing PRAW's configuration settings. **Related Classes/Methods**: @@ -112,3 +110,10 @@ 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* From aaf35edac5be1fffe97c8a1922de702ecbef288c Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Sun, 28 Sep 2025 20:25:56 +0000 Subject: [PATCH 19/23] docs: update codeboarding documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 📚 Documentation Update This commit contains updated documentation files fetched from the CodeBoarding service. ### 📊 Summary - Documentation files created/updated: 6 - JSON files created/updated: 7 - Documentation directory: .codeboarding/ - JSON directory: .codeboarding/ - Output format: .rst - Repository analyzed: https://github.com/CodeBoarding/praw - Source branch: main - Target branch: main 🤖 This commit was automatically generated by the CodeBoarding documentation update workflow. --- .codeboarding/analysis.json | 25 ++++++++++++++++--------- .codeboarding/codeboarding_version.json | 2 +- .codeboarding/overview.rst | 8 ++++++++ docs/architecture_overview/overview.rst | 8 ++++++++ 4 files changed, 33 insertions(+), 10 deletions(-) diff --git a/.codeboarding/analysis.json b/.codeboarding/analysis.json index c0c568e45..153141891 100644 --- a/.codeboarding/analysis.json +++ b/.codeboarding/analysis.json @@ -13,8 +13,7 @@ } ], "assigned_files": [ - "praw/reddit.py", - "praw/endpoints.py" + "praw/reddit.py" ], "can_expand": true }, @@ -32,7 +31,7 @@ "assigned_files": [ "praw/config.py" ], - "can_expand": false + "can_expand": true }, { "name": "Low-Level API Connector", @@ -93,6 +92,12 @@ "praw/models/subreddits.py", "praw/models/stylesheet.py", "praw/models/auth.py", + "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/reddit/__init__.py", "praw/models/reddit/submission.py", "praw/models/reddit/widgets.py", @@ -140,12 +145,6 @@ } ], "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", @@ -177,6 +176,7 @@ "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", @@ -184,6 +184,13 @@ ], "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)", diff --git a/.codeboarding/codeboarding_version.json b/.codeboarding/codeboarding_version.json index 163ee246e..032b44d72 100644 --- a/.codeboarding/codeboarding_version.json +++ b/.codeboarding/codeboarding_version.json @@ -1,4 +1,4 @@ { - "commit_hash": "de461083353c3e41a64f14ec289d02396f18db39", + "commit_hash": "090164fb6f365f6fd83ea6ad67fe82d29e1df408", "code_boarding_version": "0.2.0" } diff --git a/.codeboarding/overview.rst b/.codeboarding/overview.rst index 1685abdc7..3b93e2ba9 100644 --- a/.codeboarding/overview.rst +++ b/.codeboarding/overview.rst @@ -12,6 +12,7 @@ Overview Listing_Streaming["Listing & Streaming"] 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 @@ -117,3 +118,10 @@ 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/architecture_overview/overview.rst b/docs/architecture_overview/overview.rst index 1685abdc7..3b93e2ba9 100644 --- a/docs/architecture_overview/overview.rst +++ b/docs/architecture_overview/overview.rst @@ -12,6 +12,7 @@ Overview Listing_Streaming["Listing & Streaming"] 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 @@ -117,3 +118,10 @@ 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* From dfc529df9bae4992a2e446efc1c98f6fddf006be Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Sun, 5 Oct 2025 20:23:22 +0000 Subject: [PATCH 20/23] docs: update codeboarding documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 📚 Documentation Update This commit contains updated documentation files fetched from the CodeBoarding service. ### 📊 Summary - Documentation files created/updated: 6 - JSON files created/updated: 7 - Documentation directory: .codeboarding/ - JSON directory: .codeboarding/ - Output format: .rst - Repository analyzed: https://github.com/CodeBoarding/praw - Source branch: main - Target branch: main 🤖 This commit was automatically generated by the CodeBoarding documentation update workflow. --- .codeboarding/analysis.json | 21 ++++++++++++++------- .codeboarding/codeboarding_version.json | 2 +- .codeboarding/overview.rst | 8 ++++++++ docs/architecture_overview/overview.rst | 8 ++++++++ 4 files changed, 31 insertions(+), 8 deletions(-) diff --git a/.codeboarding/analysis.json b/.codeboarding/analysis.json index 153141891..3fc8c186a 100644 --- a/.codeboarding/analysis.json +++ b/.codeboarding/analysis.json @@ -13,7 +13,9 @@ } ], "assigned_files": [ - "praw/reddit.py" + "praw/reddit.py", + "praw/endpoints.py", + "praw/models/auth.py" ], "can_expand": true }, @@ -31,7 +33,7 @@ "assigned_files": [ "praw/config.py" ], - "can_expand": true + "can_expand": false }, { "name": "Low-Level API Connector", @@ -78,7 +80,6 @@ "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", @@ -87,11 +88,9 @@ "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/list/moderated.py", "praw/models/list/__init__.py", "praw/models/list/base.py", @@ -176,11 +175,12 @@ "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" + "praw/util/snake.py", + "praw/models/util.py", + "praw/models/helpers.py" ], "can_expand": false }, @@ -191,6 +191,13 @@ "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)", diff --git a/.codeboarding/codeboarding_version.json b/.codeboarding/codeboarding_version.json index 032b44d72..5e5658bb6 100644 --- a/.codeboarding/codeboarding_version.json +++ b/.codeboarding/codeboarding_version.json @@ -1,4 +1,4 @@ { - "commit_hash": "090164fb6f365f6fd83ea6ad67fe82d29e1df408", + "commit_hash": "aaf35edac5be1fffe97c8a1922de702ecbef288c", "code_boarding_version": "0.2.0" } diff --git a/.codeboarding/overview.rst b/.codeboarding/overview.rst index 3b93e2ba9..f5bd4049b 100644 --- a/.codeboarding/overview.rst +++ b/.codeboarding/overview.rst @@ -13,6 +13,7 @@ Overview 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 @@ -125,3 +126,10 @@ 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/architecture_overview/overview.rst b/docs/architecture_overview/overview.rst index 3b93e2ba9..f5bd4049b 100644 --- a/docs/architecture_overview/overview.rst +++ b/docs/architecture_overview/overview.rst @@ -13,6 +13,7 @@ Overview 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 @@ -125,3 +126,10 @@ 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* From 38807c47c93eb29b7c540e44196a7adf38433464 Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Sun, 12 Oct 2025 20:26:28 +0000 Subject: [PATCH 21/23] docs: update codeboarding documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 📚 Documentation Update This commit contains updated documentation files fetched from the CodeBoarding service. ### 📊 Summary - Documentation files created/updated: 7 - JSON files created/updated: 8 - Documentation directory: .codeboarding/ - JSON directory: .codeboarding/ - Output format: .rst - Repository analyzed: https://github.com/CodeBoarding/praw - Source branch: main - Target branch: main 🤖 This commit was automatically generated by the CodeBoarding documentation update workflow. --- .codeboarding/Configuration_Manager.json | 49 +++++++++++++++++ .codeboarding/Configuration_Manager.rst | 52 +++++++++++++++++++ .codeboarding/analysis.json | 31 ++++++----- .codeboarding/codeboarding_version.json | 2 +- .codeboarding/overview.rst | 11 ++++ .../Configuration_Manager.rst | 33 ++++-------- docs/architecture_overview/overview.rst | 11 ++++ 7 files changed, 152 insertions(+), 37 deletions(-) create mode 100644 .codeboarding/Configuration_Manager.json create mode 100644 .codeboarding/Configuration_Manager.rst diff --git a/.codeboarding/Configuration_Manager.json b/.codeboarding/Configuration_Manager.json new file mode 100644 index 000000000..3266fd635 --- /dev/null +++ b/.codeboarding/Configuration_Manager.json @@ -0,0 +1,49 @@ +{ + "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 + } + ], + "assigned_files": [ + "praw/config.py" + ], + "can_expand": true + }, + { + "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 + } + ], + "assigned_files": [], + "can_expand": true + }, + { + "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": "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/analysis.json b/.codeboarding/analysis.json index 3fc8c186a..40cfe35e2 100644 --- a/.codeboarding/analysis.json +++ b/.codeboarding/analysis.json @@ -14,8 +14,7 @@ ], "assigned_files": [ "praw/reddit.py", - "praw/endpoints.py", - "praw/models/auth.py" + "praw/endpoints.py" ], "can_expand": true }, @@ -33,7 +32,7 @@ "assigned_files": [ "praw/config.py" ], - "can_expand": false + "can_expand": true }, { "name": "Low-Level API Connector", @@ -80,6 +79,7 @@ "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", @@ -88,15 +88,11 @@ "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/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/auth.py", "praw/models/reddit/__init__.py", "praw/models/reddit/submission.py", "praw/models/reddit/widgets.py", @@ -144,6 +140,12 @@ } ], "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", @@ -178,9 +180,7 @@ "praw/exceptions.py", "praw/util/__init__.py", "praw/util/cache.py", - "praw/util/snake.py", - "praw/models/util.py", - "praw/models/helpers.py" + "praw/util/snake.py" ], "can_expand": false }, @@ -198,6 +198,13 @@ "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)", diff --git a/.codeboarding/codeboarding_version.json b/.codeboarding/codeboarding_version.json index 5e5658bb6..afaeb0252 100644 --- a/.codeboarding/codeboarding_version.json +++ b/.codeboarding/codeboarding_version.json @@ -1,4 +1,4 @@ { - "commit_hash": "aaf35edac5be1fffe97c8a1922de702ecbef288c", + "commit_hash": "dfc529df9bae4992a2e446efc1c98f6fddf006be", "code_boarding_version": "0.2.0" } diff --git a/.codeboarding/overview.rst b/.codeboarding/overview.rst index f5bd4049b..5d74b0aab 100644 --- a/.codeboarding/overview.rst +++ b/.codeboarding/overview.rst @@ -14,6 +14,7 @@ Overview 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 @@ -23,6 +24,7 @@ Overview 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" @@ -56,6 +58,8 @@ The primary interface for interacting with the Reddit API, managing authenticati Configuration Manager ^^^^^^^^^^^^^^^^^^^^^ +:ref:`Expand ` + Manages loading and accessing PRAW's configuration settings. **Related Classes/Methods**: @@ -133,3 +137,10 @@ 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/architecture_overview/Configuration_Manager.rst b/docs/architecture_overview/Configuration_Manager.rst index 49a06b7d4..edd120c59 100644 --- a/docs/architecture_overview/Configuration_Manager.rst +++ b/docs/architecture_overview/Configuration_Manager.rst @@ -5,15 +5,9 @@ Configuration Manager graph LR Configuration_Manager["Configuration Manager"] - High_Level_API_Interface["High-Level API Interface"] - Authentication_Module["Authentication Module"] + Reddit_API_Client["Reddit API Client"] Unclassified["Unclassified"] - Configuration_Manager -- "provides configuration to" --> High_Level_API_Interface - Configuration_Manager -- "provides configuration to" --> Authentication_Module - High_Level_API_Interface -- "consumes configuration from" --> Configuration_Manager - High_Level_API_Interface -- "utilizes" --> Authentication_Module - Authentication_Module -- "consumes credentials from" --> Configuration_Manager - Authentication_Module -- "provides authenticated sessions/tokens to" --> High_Level_API_Interface + 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| @@ -28,36 +22,27 @@ Configuration Manager Details ------- -The PRAW library's core architecture is built around three central components: the `Configuration Manager`, the `High-Level API Interface`, and the `Authentication Module`. The `Configuration Manager` acts as the foundational layer, centralizing and providing all necessary configuration settings, including API credentials and user agent strings, to other components. The `High-Level API Interface` serves as the primary entry point for users, orchestrating API requests and relying on the `Configuration Manager` for initial setup. Crucially, the `Authentication Module` handles secure interactions with the Reddit API by managing OAuth2 flows, acquiring and refreshing access tokens, and utilizing credentials supplied by the `Configuration Manager`. This modular design ensures a clear separation of concerns, promoting maintainability and robust interaction with the Reddit API. +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 is the core component responsible for loading, parsing, and validating configuration settings for PRAW. It sources settings from various locations, including `praw.ini` files and environment variables, and provides a unified, structured interface for other parts of the library to access critical values such as API credentials, user agent strings, and other operational parameters. It also handles the application of default values when specific settings are not provided. This component is fundamental as it centralizes all configurable parameters, ensuring consistent and correct behavior across the API client. +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 `_ +* praw.config.Config -High-Level API Interface -^^^^^^^^^^^^^^^^^^^^^^^^ +Reddit API Client +^^^^^^^^^^^^^^^^^ -This component represents the primary entry point for users to interact with the Reddit API. It encapsulates the overall client functionality and orchestrates API requests. It relies on the `Configuration Manager` to initialize itself with necessary settings like the user agent and other API-specific parameters, ensuring the client is properly configured before making any calls. +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 `_ - -Authentication Module -^^^^^^^^^^^^^^^^^^^^^ - -This conceptual component is responsible for handling the authentication process with the Reddit API, typically involving OAuth2 flows. It manages the acquisition, storage, and refreshing of access tokens and utilizes credentials (e.g., `client_id`, `client_secret`) provided by the `Configuration Manager` to establish authenticated sessions. This module is critical for securing API interactions. - -**Related Classes/Methods**: - -* `praw.models.auth.Auth `_ +* praw.Reddit.Reddit:57-901 Unclassified ^^^^^^^^^^^^ diff --git a/docs/architecture_overview/overview.rst b/docs/architecture_overview/overview.rst index f5bd4049b..5d74b0aab 100644 --- a/docs/architecture_overview/overview.rst +++ b/docs/architecture_overview/overview.rst @@ -14,6 +14,7 @@ Overview 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 @@ -23,6 +24,7 @@ Overview 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" @@ -56,6 +58,8 @@ The primary interface for interacting with the Reddit API, managing authenticati Configuration Manager ^^^^^^^^^^^^^^^^^^^^^ +:ref:`Expand ` + Manages loading and accessing PRAW's configuration settings. **Related Classes/Methods**: @@ -133,3 +137,10 @@ 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* From ea80ca676fe8ba004e01e2c2cd3b178110006f2f Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Sun, 19 Oct 2025 20:25:06 +0000 Subject: [PATCH 22/23] docs: update codeboarding documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 📚 Documentation Update This commit contains updated documentation files fetched from the CodeBoarding service. ### 📊 Summary - Documentation files created/updated: 7 - JSON files created/updated: 8 - Documentation directory: .codeboarding/ - JSON directory: .codeboarding/ - Output format: .rst - Repository analyzed: https://github.com/CodeBoarding/praw - Source branch: main - Target branch: main 🤖 This commit was automatically generated by the CodeBoarding documentation update workflow. --- .codeboarding/Configuration_Manager.json | 14 +++----------- .codeboarding/analysis.json | 11 +++++++++-- .codeboarding/codeboarding_version.json | 2 +- .codeboarding/overview.rst | 8 ++++++++ docs/architecture_overview/overview.rst | 8 ++++++++ 5 files changed, 29 insertions(+), 14 deletions(-) diff --git a/.codeboarding/Configuration_Manager.json b/.codeboarding/Configuration_Manager.json index 3266fd635..90a52a5c6 100644 --- a/.codeboarding/Configuration_Manager.json +++ b/.codeboarding/Configuration_Manager.json @@ -11,11 +11,7 @@ "reference_start_line": 52, "reference_end_line": 52 } - ], - "assigned_files": [ - "praw/config.py" - ], - "can_expand": true + ] }, { "name": "Reddit API Client", @@ -27,16 +23,12 @@ "reference_start_line": 57, "reference_end_line": 901 } - ], - "assigned_files": [], - "can_expand": true + ] }, { "name": "Unclassified", "description": "Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies)", - "referenced_source_code": [], - "assigned_files": [], - "can_expand": false + "referenced_source_code": [] } ], "components_relations": [ diff --git a/.codeboarding/analysis.json b/.codeboarding/analysis.json index 40cfe35e2..f66b30b57 100644 --- a/.codeboarding/analysis.json +++ b/.codeboarding/analysis.json @@ -13,8 +13,7 @@ } ], "assigned_files": [ - "praw/reddit.py", - "praw/endpoints.py" + "praw/reddit.py" ], "can_expand": true }, @@ -177,6 +176,7 @@ "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", @@ -205,6 +205,13 @@ "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)", diff --git a/.codeboarding/codeboarding_version.json b/.codeboarding/codeboarding_version.json index afaeb0252..e7e6c2fab 100644 --- a/.codeboarding/codeboarding_version.json +++ b/.codeboarding/codeboarding_version.json @@ -1,4 +1,4 @@ { - "commit_hash": "dfc529df9bae4992a2e446efc1c98f6fddf006be", + "commit_hash": "38807c47c93eb29b7c540e44196a7adf38433464", "code_boarding_version": "0.2.0" } diff --git a/.codeboarding/overview.rst b/.codeboarding/overview.rst index 5d74b0aab..791a708b0 100644 --- a/.codeboarding/overview.rst +++ b/.codeboarding/overview.rst @@ -15,6 +15,7 @@ Overview 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 @@ -144,3 +145,10 @@ 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/architecture_overview/overview.rst b/docs/architecture_overview/overview.rst index 5d74b0aab..791a708b0 100644 --- a/docs/architecture_overview/overview.rst +++ b/docs/architecture_overview/overview.rst @@ -15,6 +15,7 @@ Overview 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 @@ -144,3 +145,10 @@ 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* From c595221bd4e1eee10beca3646b04b0133dbf02ca Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Sun, 26 Oct 2025 20:25:30 +0000 Subject: [PATCH 23/23] docs: update codeboarding documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 📚 Documentation Update This commit contains updated documentation files fetched from the CodeBoarding service. ### 📊 Summary - Documentation files created/updated: 7 - JSON files created/updated: 8 - Documentation directory: .codeboarding/ - JSON directory: .codeboarding/ - Output format: .rst - Repository analyzed: https://github.com/CodeBoarding/praw - Source branch: main - Target branch: main 🤖 This commit was automatically generated by the CodeBoarding documentation update workflow. --- .codeboarding/analysis.json | 11 +++++++++-- .codeboarding/codeboarding_version.json | 2 +- .codeboarding/overview.rst | 8 ++++++++ docs/architecture_overview/overview.rst | 8 ++++++++ 4 files changed, 26 insertions(+), 3 deletions(-) diff --git a/.codeboarding/analysis.json b/.codeboarding/analysis.json index f66b30b57..651b46073 100644 --- a/.codeboarding/analysis.json +++ b/.codeboarding/analysis.json @@ -13,7 +13,8 @@ } ], "assigned_files": [ - "praw/reddit.py" + "praw/reddit.py", + "praw/endpoints.py" ], "can_expand": true }, @@ -176,7 +177,6 @@ "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", @@ -212,6 +212,13 @@ "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)", diff --git a/.codeboarding/codeboarding_version.json b/.codeboarding/codeboarding_version.json index e7e6c2fab..b1c4a713b 100644 --- a/.codeboarding/codeboarding_version.json +++ b/.codeboarding/codeboarding_version.json @@ -1,4 +1,4 @@ { - "commit_hash": "38807c47c93eb29b7c540e44196a7adf38433464", + "commit_hash": "ea80ca676fe8ba004e01e2c2cd3b178110006f2f", "code_boarding_version": "0.2.0" } diff --git a/.codeboarding/overview.rst b/.codeboarding/overview.rst index 791a708b0..d4154c00b 100644 --- a/.codeboarding/overview.rst +++ b/.codeboarding/overview.rst @@ -16,6 +16,7 @@ Overview 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 @@ -152,3 +153,10 @@ 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/architecture_overview/overview.rst b/docs/architecture_overview/overview.rst index 791a708b0..d4154c00b 100644 --- a/docs/architecture_overview/overview.rst +++ b/docs/architecture_overview/overview.rst @@ -16,6 +16,7 @@ Overview 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 @@ -152,3 +153,10 @@ 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*