praw-dev · ivanmilevtues · Jun 9, 2025
diff --git a/.codeboarding/Content & Listing Management.md 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-%[email protected]?style=flat-square)](mailto:[email protected])
+
+## 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**:
+
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/reddit.py#L57-L901" target="_blank" rel="noopener noreferrer">`praw.praw.reddit.Reddit` (57:901)</a>
+
+
+### 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**:
+
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/listing/generator.py#L17-L103" target="_blank" rel="noopener noreferrer">`praw.praw.models.listing.generator.ListingGenerator` (17:103)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/listing/domain.py#L14-L25" target="_blank" rel="noopener noreferrer">`praw.praw.models.listing.domain.DomainListing` (14:25)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/listing/mixins/redditor.py#L18-L32" target="_blank" rel="noopener noreferrer">`praw.praw.models.listing.mixins.redditor.SubListing` (18:32)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/listing/mixins/redditor.py#L35-L185" target="_blank" rel="noopener noreferrer">`praw.praw.models.listing.mixins.redditor.RedditorListingMixin` (35:185)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/listing/mixins/subreddit.py#L20-L46" target="_blank" rel="noopener noreferrer">`praw.praw.models.listing.mixins.subreddit.CommentHelper` (20:46)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/listing/mixins/subreddit.py#L49-L73" target="_blank" rel="noopener noreferrer">`praw.praw.models.listing.mixins.subreddit.SubredditListingMixin` (49:73)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/listing/mixins/rising.py#L17-L34" target="_blank" rel="noopener noreferrer">`praw.praw.models.listing.mixins.rising.RisingListingMixin` (17:34)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/listing/mixins/base.py#L15-L149" target="_blank" rel="noopener noreferrer">`praw.praw.models.listing.mixins.base.BaseListingMixin` (15:149)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/listing/mixins/submission.py#L17-L42" target="_blank" rel="noopener noreferrer">`praw.praw.models.listing.mixins.submission.SubmissionListingMixin` (17:42)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/util.py#L10-L190" target="_blank" rel="noopener noreferrer">`praw.praw.models.util` (10:190)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/comment_forest.py#L15-L202" target="_blank" rel="noopener noreferrer">`praw.praw.models.comment_forest.CommentForest` (15:202)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/reddit/comment.py#L19-L311" target="_blank" rel="noopener noreferrer">`praw.praw.models.reddit.comment.Comment` (19:311)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/reddit/comment.py#L314-L350" target="_blank" rel="noopener noreferrer">`praw.praw.models.reddit.comment.CommentModeration` (314:350)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/reddit/more.py#L14-L87" target="_blank" rel="noopener noreferrer">`praw.praw.models.reddit.more.MoreComments` (14:87)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/reddit/submission.py#L395-L916" target="_blank" rel="noopener noreferrer">`praw.praw.models.reddit.submission.Submission` (395:916)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/reddit/submission.py#L40-L90" target="_blank" rel="noopener noreferrer">`praw.praw.models.reddit.submission.SubmissionFlair` (40:90)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/reddit/submission.py#L93-L392" target="_blank" rel="noopener noreferrer">`praw.praw.models.reddit.submission.SubmissionModeration` (93:392)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/helpers.py#L20-L133" target="_blank" rel="noopener noreferrer">`praw.praw.models.helpers.DraftHelper` (20:133)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/reddit/draft.py#L17-L292" target="_blank" rel="noopener noreferrer">`praw.praw.models.reddit.draft.Draft` (17:292)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/reddit/poll.py#L47-L112" target="_blank" rel="noopener noreferrer">`praw.praw.models.reddit.poll.PollData` (47:112)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/reddit/poll.py#L11-L44" target="_blank" rel="noopener noreferrer">`praw.praw.models.reddit.poll.PollOption` (11:44)</a>
+
+
+### Listing Generators
+A core component responsible for iterating and fetching paginated lists of various Reddit objects.
+
+
+**Related Classes/Methods**:
+
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/listing/generator.py#L17-L103" target="_blank" rel="noopener noreferrer">`praw.models.listing.generator.ListingGenerator` (17:103)</a>
+
+
+### Comment Objects
+Represents individual Reddit comments, providing methods for interaction and retrieval of related data.
+
+
+**Related Classes/Methods**:
+
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/reddit/comment.py#L19-L311" target="_blank" rel="noopener noreferrer">`praw.praw.models.reddit.comment.Comment` (19:311)</a>
+
+
+### Submission Objects
+Represents Reddit posts (submissions), offering functionalities for content manipulation and moderation.
+
+
+**Related Classes/Methods**:
+
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/reddit/submission.py#L395-L916" target="_blank" rel="noopener noreferrer">`praw.praw.models.reddit.submission.Submission` (395:916)</a>
+
+
+### 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**:
+
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/reddit/redditor.py#L21-L409" target="_blank" rel="noopener noreferrer">`praw.praw.models.reddit.redditor.Redditor` (21:409)</a>
+
+
+### Inbox Manager
+Manages the authenticated user's Reddit inbox, allowing retrieval of messages, comment replies, and mentions.
+
+
+**Related Classes/Methods**:
+
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/inbox.py#L18-L324" target="_blank" rel="noopener noreferrer">`praw.praw.models.inbox.Inbox` (18:324)</a>
+
+
+### Draft Management
+Provides utilities for creating and managing submission drafts.
+
+
+**Related Classes/Methods**:
+
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/helpers.py#L20-L133" target="_blank" rel="noopener noreferrer">`praw.praw.models.helpers.DraftHelper` (20:133)</a>
+
+
+### Stream Utilities
+Offers helper functions for continuously streaming new Reddit content, such as comments or submissions.
+
+
+**Related Classes/Methods**:
+
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/util.py#L36-L163" target="_blank" rel="noopener noreferrer">`praw.praw.models.util.stream_generator` (36:163)</a>
+
+
+### 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**:
+
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/listing/mixins/base.py#L15-L149" target="_blank" rel="noopener noreferrer">`praw.praw.models.listing.mixins.base.BaseListingMixin` (15:149)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/listing/mixins/redditor.py#L35-L185" target="_blank" rel="noopener noreferrer">`praw.praw.models.listing.mixins.redditor.RedditorListingMixin` (35:185)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/praw/models/listing/mixins/subreddit.py#L49-L73" target="_blank" rel="noopener noreferrer">`praw.praw.models.listing.mixins.subreddit.SubredditListingMixin` (49:73)</a>
+
+
+
+
+### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq)
diff --git a/.codeboarding/Development & Build Tools.md 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-%[email protected]?style=flat-square)](mailto:[email protected])
+
+## 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**:
+
+- <a href="https://github.com/praw-dev/praw/blob/master/pre_push.py#L2-L80" target="_blank" rel="noopener noreferrer">`praw.pre_push` (2:80)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/pre_push.py#L58-L98" target="_blank" rel="noopener noreferrer">`praw.pre_push.main` (58:98)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/pre_push.py#L32-L45" target="_blank" rel="noopener noreferrer">`praw.pre_push.run_static` (32:45)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/pre_push.py#L48-L55" target="_blank" rel="noopener noreferrer">`praw.pre_push.run_unit` (48:55)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/pre_push.py#L10-L29" target="_blank" rel="noopener noreferrer">`praw.pre_push.do_process` (10:29)</a>
+
+
+### 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**:
+
+- <a href="https://github.com/praw-dev/praw/blob/master/tools/static_word_checks.py#L5-L100" target="_blank" rel="noopener noreferrer">`praw.tools.static_word_checks` (5:100)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/tools/static_word_checks.py#L120-L140" target="_blank" rel="noopener noreferrer">`praw.tools.static_word_checks.main` (120:140)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/tools/static_word_checks.py#L8-L117" target="_blank" rel="noopener noreferrer">`praw.tools.static_word_checks.StaticChecker` (8:117)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/tools/static_word_checks.py#L75-L117" target="_blank" rel="noopener noreferrer">`praw.tools.static_word_checks.StaticChecker.run_checks` (75:117)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/tools/static_word_checks.py#L27-L55" target="_blank" rel="noopener noreferrer">`praw.tools.static_word_checks.StaticChecker.check_for_double_syntax` (27:55)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/tools/static_word_checks.py#L57-L73" target="_blank" rel="noopener noreferrer">`praw.tools.static_word_checks.StaticChecker.check_for_noreturn` (57:73)</a>
+
+
+### 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**:
+
+- <a href="https://github.com/praw-dev/praw/blob/master/tools/check_documentation.py#L5-L70" target="_blank" rel="noopener noreferrer">`praw.tools.check_documentation` (5:70)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/tools/check_documentation.py#L80-L81" target="_blank" rel="noopener noreferrer">`praw.tools.check_documentation.main` (80:81)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/tools/check_documentation.py#L16-L77" target="_blank" rel="noopener noreferrer">`praw.tools.check_documentation.DocumentationChecker` (16:77)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/tools/check_documentation.py#L46-L77" target="_blank" rel="noopener noreferrer">`praw.tools.check_documentation.DocumentationChecker.check` (46:77)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/tools/check_documentation.py#L36-L43" target="_blank" rel="noopener noreferrer">`praw.tools.check_documentation.DocumentationChecker.discover_subclasses` (36:43)</a>
+
+
+### 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**:
+
+- <a href="https://github.com/praw-dev/praw/blob/master/tools/set_active_docs.py#L5-L80" target="_blank" rel="noopener noreferrer">`praw.tools.set_active_docs` (5:80)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/tools/set_active_docs.py#L32-L90" target="_blank" rel="noopener noreferrer">`praw.tools.set_active_docs.main` (32:90)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/tools/set_active_docs.py#L14-L29" target="_blank" rel="noopener noreferrer">`praw.tools.set_active_docs.fetch_versions` (14:29)</a>
+
+
+### 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**:
+
+- <a href="https://github.com/praw-dev/praw/blob/master/tools/set_version.py#L5-L100" target="_blank" rel="noopener noreferrer">`praw.tools.set_version` (5:100)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/tools/set_version.py#L64-L70" target="_blank" rel="noopener noreferrer">`praw.tools.set_version.main` (64:70)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/tools/set_version.py#L32-L33" target="_blank" rel="noopener noreferrer">`praw.tools.set_version.handle_unreleased` (32:33)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/tools/set_version.py#L36-L40" target="_blank" rel="noopener noreferrer">`praw.tools.set_version.handle_version` (36:40)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/tools/set_version.py#L15-L29" target="_blank" rel="noopener noreferrer">`praw.tools.set_version.add_unreleased_to_changelog` (15:29)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/tools/set_version.py#L43-L61" target="_blank" rel="noopener noreferrer">`praw.tools.set_version.increment_development_version` (43:61)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/tools/set_version.py#L107-L112" target="_blank" rel="noopener noreferrer">`praw.tools.set_version.valid_version` (107:112)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/tools/set_version.py#L73-L88" target="_blank" rel="noopener noreferrer">`praw.tools.set_version.update_changelog` (73:88)</a>
+- <a href="https://github.com/praw-dev/praw/blob/master/tools/set_version.py#L91-L104" target="_blank" rel="noopener noreferrer">`praw.tools.set_version.update_package` (91:104)</a>
+
+
+
+
+### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq)