Skip to content

Commit 55a62c2

Browse files
actions-useractions-user
committed
docs: update codeboarding documentation
## 📚 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.
1 parent 5dcaebd commit 55a62c2

9 files changed

Lines changed: 247 additions & 72 deletions

‎.codeboarding/API_Client_Core.rst‎

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
High-level diagram representation of: praw
2-
==========================================
1+
Api Client Core
2+
===============
33

44
.. mermaid::
55

@@ -21,12 +21,12 @@ High-level diagram representation of: praw
2121
Request_Executor -- "returns raw response to" --> Response_Objectifier
2222
Response_Objectifier -- "transforms for" --> API_Operation_Methods
2323
API_Operation_Methods -- "consults" --> Rate_Limit_Manager
24-
click API_Client_Core href "https://github.com/CodeBoarding/praw/blob/main/.codeboarding/API_Client_Core.html" "Details"
24+
click API_Client_Core href "https://github.com/praw-dev/praw/blob/main/.codeboarding/API_Client_Core.html" "Details"
2525

2626
| |codeboarding-badge| |demo-badge| |contact-badge|
2727
2828
.. |codeboarding-badge| image:: https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square
29-
:target: https://github.com/CodeBoarding/GeneratedOnBoardings
29+
:target: https://github.com/CodeBoarding/CodeBoarding
3030
.. |demo-badge| image:: https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square
3131
:target: https://www.codeboarding.org/demo
3232
.. |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
4646

4747
**Related Classes/Methods**:
4848

49-
* `QName:`praw.reddit.Reddit` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py`, Lines:(57:901) <https://github.com/CodeBoarding/praw/blob/main/.codeboarding/praw/reddit.py#L57-L901>`_
49+
* `praw.reddit.Reddit:57-901 <https://github.com/praw-dev/praw/blob/main/praw/reddit.py#L57-L901>`_
5050

5151
Client Initializer
5252
^^^^^^^^^^^^^^^^^^
@@ -55,9 +55,9 @@ Sets up the API Client Core instance, including configuring the underlying HTTP
5555

5656
**Related Classes/Methods**:
5757

58-
* `QName:`praw.reddit.Reddit.__init__` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` <https://github.com/CodeBoarding/praw/blob/main/.codeboarding/praw/reddit.py#L0-L0>`_
59-
* `QName:`praw.reddit._prepare_prawcore` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py`, Lines:(527:546) <https://github.com/CodeBoarding/praw/blob/main/.codeboarding/praw/reddit.py#L527-L546>`_
60-
* `QName:`praw.reddit._prepare_objector` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py`, Lines:(479:525) <https://github.com/CodeBoarding/praw/blob/main/.codeboarding/praw/reddit.py#L479-L525>`_
58+
* `praw.reddit.Reddit.__init__ <https://github.com/praw-dev/praw/blob/main/praw/reddit.py>`_
59+
* `praw.reddit._prepare_prawcore:527-546 <https://github.com/praw-dev/praw/blob/main/praw/reddit.py#L527-L546>`_
60+
* `praw.reddit._prepare_objector:479-525 <https://github.com/praw-dev/praw/blob/main/praw/reddit.py#L479-L525>`_
6161

6262
Request Executor
6363
^^^^^^^^^^^^^^^^
@@ -66,7 +66,7 @@ Executes the raw HTTP requests to the Reddit API, handling the low-level communi
6666

6767
**Related Classes/Methods**:
6868

69-
* `QName:`praw.reddit.Reddit.request` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` <https://github.com/CodeBoarding/praw/blob/main/.codeboarding/praw/reddit.py#L0-L0>`_
69+
* `praw.reddit.Reddit.request <https://github.com/praw-dev/praw/blob/main/praw/reddit.py>`_
7070

7171
Response Objectifier
7272
^^^^^^^^^^^^^^^^^^^^
@@ -75,7 +75,7 @@ Transforms the raw JSON responses from the API into structured PRAW Python objec
7575

7676
**Related Classes/Methods**:
7777

78-
* `QName:`praw.reddit.Reddit._objectify_request` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` <https://github.com/CodeBoarding/praw/blob/main/.codeboarding/praw/reddit.py#L0-L0>`_
78+
* `praw.reddit.Reddit._objectify_request <https://github.com/praw-dev/praw/blob/main/praw/reddit.py>`_
7979

8080
Rate Limit Manager
8181
^^^^^^^^^^^^^^^^^^
@@ -84,7 +84,7 @@ Monitors and enforces Reddit's API rate limits, pausing requests when necessary
8484

8585
**Related Classes/Methods**:
8686

87-
* `QName:`praw.reddit.Reddit._handle_rate_limit` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` <https://github.com/CodeBoarding/praw/blob/main/.codeboarding/praw/reddit.py#L0-L0>`_
87+
* `praw.reddit.Reddit._handle_rate_limit <https://github.com/praw-dev/praw/blob/main/praw/reddit.py>`_
8888

8989
API Operation Methods
9090
^^^^^^^^^^^^^^^^^^^^^
@@ -93,11 +93,11 @@ Provide specific, high-level methods for common API operations (e.g., fetching d
9393

9494
**Related Classes/Methods**:
9595

96-
* `QName:`praw.reddit.Reddit.get` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` <https://github.com/CodeBoarding/praw/blob/main/.codeboarding/praw/reddit.py#L0-L0>`_
97-
* `QName:`praw.reddit.Reddit.post` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` <https://github.com/CodeBoarding/praw/blob/main/.codeboarding/praw/reddit.py#L0-L0>`_
98-
* `QName:`praw.reddit.Reddit.delete` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` <https://github.com/CodeBoarding/praw/blob/main/.codeboarding/praw/reddit.py#L0-L0>`_
99-
* `QName:`praw.reddit.Reddit.patch` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` <https://github.com/CodeBoarding/praw/blob/main/.codeboarding/praw/reddit.py#L0-L0>`_
100-
* `QName:`praw.reddit.Reddit.put` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py` <https://github.com/CodeBoarding/praw/blob/main/.codeboarding/praw/reddit.py#L0-L0>`_
96+
* `praw.reddit.Reddit.get <https://github.com/praw-dev/praw/blob/main/praw/reddit.py>`_
97+
* `praw.reddit.Reddit.post <https://github.com/praw-dev/praw/blob/main/praw/reddit.py>`_
98+
* `praw.reddit.Reddit.delete <https://github.com/praw-dev/praw/blob/main/praw/reddit.py>`_
99+
* `praw.reddit.Reddit.patch <https://github.com/praw-dev/praw/blob/main/praw/reddit.py>`_
100+
* `praw.reddit.Reddit.put <https://github.com/praw-dev/praw/blob/main/praw/reddit.py>`_
101101

102102
Async Checker
103103
^^^^^^^^^^^^^
@@ -106,7 +106,7 @@ Manages and verifies the asynchronous context for operations, ensuring proper ex
106106

107107
**Related Classes/Methods**:
108108

109-
* `QName:`praw.reddit._check_for_async` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/reddit.py`, Lines:(388:411) <https://github.com/CodeBoarding/praw/blob/main/.codeboarding/praw/reddit.py#L388-L411>`_
109+
* `praw.reddit._check_for_async:388-411 <https://github.com/praw-dev/praw/blob/main/praw/reddit.py#L388-L411>`_
110110

111111

112112
FAQ

‎.codeboarding/Exception_Handling.json‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
{
2+
"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.",
3+
"components": [
4+
{
5+
"name": "ExceptionBase",
6+
"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.",
7+
"referenced_source_code": [
8+
{
9+
"qualified_name": "praw.exceptions.PRAWException",
10+
"reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py",
11+
"reference_start_line": 14,
12+
"reference_end_line": 15
13+
}
14+
],
15+
"can_expand": false
16+
},
17+
{
18+
"name": "ErrorItem",
19+
"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.",
20+
"referenced_source_code": [
21+
{
22+
"qualified_name": "praw.exceptions.RedditErrorItem",
23+
"reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py",
24+
"reference_start_line": 18,
25+
"reference_end_line": 71
26+
}
27+
],
28+
"can_expand": false
29+
},
30+
{
31+
"name": "ErrorParser",
32+
"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.",
33+
"referenced_source_code": [
34+
{
35+
"qualified_name": "praw.exceptions.parse_exception_list",
36+
"reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/exceptions.py",
37+
"reference_start_line": 173,
38+
"reference_end_line": 189
39+
}
40+
],
41+
"can_expand": false
42+
},
43+
{
44+
"name": "ErrorDetector",
45+
"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.",
46+
"referenced_source_code": [
47+
{
48+
"qualified_name": "praw.objector.check_error",
49+
"reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py",
50+
"reference_start_line": 20,
51+
"reference_end_line": 24
52+
}
53+
],
54+
"can_expand": false
55+
},
56+
{
57+
"name": "ExceptionFactory",
58+
"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.",
59+
"referenced_source_code": [
60+
{
61+
"qualified_name": "praw.objector.parse_error",
62+
"reference_file": "/home/ubuntu/CodeBoarding/repo/praw/praw/objector.py",
63+
"reference_start_line": 26,
64+
"reference_end_line": 48
65+
}
66+
],
67+
"can_expand": true
68+
}
69+
],
70+
"components_relations": [
71+
{
72+
"relation": "delegates error parsing to",
73+
"src_name": "ErrorDetector",
74+
"dst_name": "ExceptionFactory"
75+
},
76+
{
77+
"relation": "converts raw errors to structured items via",
78+
"src_name": "ExceptionFactory",
79+
"dst_name": "ErrorParser"
80+
},
81+
{
82+
"relation": "creates",
83+
"src_name": "ErrorParser",
84+
"dst_name": "ErrorItem"
85+
},
86+
{
87+
"relation": "raises",
88+
"src_name": "ExceptionFactory",
89+
"dst_name": "ExceptionBase"
90+
}
91+
]
92+
}

‎.codeboarding/Exception_Handling.rst‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
Exception Handling
2+
==================
3+
4+
.. mermaid::
5+
6+
graph LR
7+
ExceptionBase["ExceptionBase"]
8+
ErrorItem["ErrorItem"]
9+
ErrorParser["ErrorParser"]
10+
ErrorDetector["ErrorDetector"]
11+
ExceptionFactory["ExceptionFactory"]
12+
ErrorDetector -- "delegates error parsing to" --> ExceptionFactory
13+
ExceptionFactory -- "converts raw errors to structured items via" --> ErrorParser
14+
ErrorParser -- "creates" --> ErrorItem
15+
ExceptionFactory -- "raises" --> ExceptionBase
16+
17+
| |codeboarding-badge| |demo-badge| |contact-badge|
18+
19+
.. |codeboarding-badge| image:: https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square
20+
:target: https://github.com/CodeBoarding/CodeBoarding
21+
.. |demo-badge| image:: https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square
22+
:target: https://www.codeboarding.org/demo
23+
.. |contact-badge| image:: https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square
24+
:target: mailto:contact@codeboarding.org
25+
26+
Details
27+
-------
28+
29+
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.
30+
31+
ExceptionBase
32+
^^^^^^^^^^^^^
33+
34+
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.
35+
36+
**Related Classes/Methods**:
37+
38+
* `praw.exceptions.PRAWException:14-15 <https://github.com/praw-dev/praw/blob/main/praw/exceptions.py#L14-L15>`_
39+
40+
ErrorItem
41+
^^^^^^^^^
42+
43+
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.
44+
45+
**Related Classes/Methods**:
46+
47+
* `praw.exceptions.RedditErrorItem:18-71 <https://github.com/praw-dev/praw/blob/main/praw/exceptions.py#L18-L71>`_
48+
49+
ErrorParser
50+
^^^^^^^^^^^
51+
52+
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.
53+
54+
**Related Classes/Methods**:
55+
56+
* `praw.exceptions.parse_exception_list:173-189 <https://github.com/praw-dev/praw/blob/main/praw/exceptions.py#L173-L189>`_
57+
58+
ErrorDetector
59+
^^^^^^^^^^^^^
60+
61+
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.
62+
63+
**Related Classes/Methods**:
64+
65+
* `praw.objector.check_error:20-24 <https://github.com/praw-dev/praw/blob/main/praw/objector.py#L20-L24>`_
66+
67+
ExceptionFactory
68+
^^^^^^^^^^^^^^^^
69+
70+
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.
71+
72+
**Related Classes/Methods**:
73+
74+
* `praw.objector.parse_error:26-48 <https://github.com/praw-dev/praw/blob/main/praw/objector.py#L26-L48>`_
75+
76+
77+
FAQ
78+
---
79+
80+
`See the FAQ <https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq>`_

‎.codeboarding/Listing_Stream_Processors.rst‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
High-level diagram representation of: praw
2-
==========================================
1+
Listing Stream Processors
2+
=========================
33

44
.. mermaid::
55

@@ -24,7 +24,7 @@ High-level diagram representation of: praw
2424
| |codeboarding-badge| |demo-badge| |contact-badge|
2525
2626
.. |codeboarding-badge| image:: https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square
27-
:target: https://github.com/CodeBoarding/GeneratedOnBoardings
27+
:target: https://github.com/CodeBoarding/CodeBoarding
2828
.. |demo-badge| image:: https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square
2929
:target: https://www.codeboarding.org/demo
3030
.. |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
4242

4343
**Related Classes/Methods**:
4444

45-
* `QName:`ListingGenerator` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py`, Lines:(17:103) <https://github.com/CodeBoarding/praw/blob/main/.codeboarding/praw/models/listing/generator.py#L17-L103>`_
45+
* `ListingGenerator:17-103 <https://github.com/praw-dev/praw/blob/main/praw/models/listing/generator.py#L17-L103>`_
4646

4747
ListingBatchFetcher
4848
^^^^^^^^^^^^^^^^^^^
@@ -51,7 +51,7 @@ Responsible for fetching a single batch of items from the Reddit API using the u
5151

5252
**Related Classes/Methods**:
5353

54-
* `QName:`ListingBatchFetcher` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py`, Lines:(1:1000) <https://github.com/CodeBoarding/praw/blob/main/.codeboarding/praw/models/listing/generator.py#L1-L1000>`_
54+
* `ListingBatchFetcher:1-1000 <https://github.com/praw-dev/praw/blob/main/praw/models/listing/generator.py#L1-L1000>`_
5555

5656
ListingDataExtractor
5757
^^^^^^^^^^^^^^^^^^^^
@@ -60,7 +60,7 @@ Parses the raw JSON response received from the API, isolating and returning the
6060

6161
**Related Classes/Methods**:
6262

63-
* `QName:`ListingDataExtractor` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/generator.py`, Lines:(1:1000) <https://github.com/CodeBoarding/praw/blob/main/.codeboarding/praw/models/listing/generator.py#L1-L1000>`_
63+
* `ListingDataExtractor:1-1000 <https://github.com/praw-dev/praw/blob/main/praw/models/listing/generator.py#L1-L1000>`_
6464

6565
ListingParameterMixin
6666
^^^^^^^^^^^^^^^^^^^^^
@@ -69,7 +69,7 @@ Provides common methods for constructing API paths and parameters required for v
6969

7070
**Related Classes/Methods**:
7171

72-
* `QName:`ListingParameterMixin` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/listing/mixins/base.py`, Lines:(1:1000) <https://github.com/CodeBoarding/praw/blob/main/.codeboarding/praw/models/listing/mixins/base.py#L1-L1000>`_
72+
* `ListingParameterMixin:1-1000 <https://github.com/praw-dev/praw/blob/main/praw/models/listing/mixins/base.py#L1-L1000>`_
7373

7474
StreamProcessor
7575
^^^^^^^^^^^^^^^
@@ -78,7 +78,7 @@ Implements the foundational logic for consuming continuous data streams from the
7878

7979
**Related Classes/Methods**:
8080

81-
* `QName:`StreamProcessor` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/util.py`, Lines:(1:1000) <https://github.com/CodeBoarding/praw/blob/main/.codeboarding/praw/models/util.py#L1-L1000>`_
81+
* `StreamProcessor:1-1000 <https://github.com/praw-dev/praw/blob/main/praw/models/util.py#L1-L1000>`_
8282

8383
StreamUniquenessManager
8484
^^^^^^^^^^^^^^^^^^^^^^^
@@ -87,7 +87,7 @@ Maintains a limited set of recently seen items to ensure uniqueness within a dat
8787

8888
**Related Classes/Methods**:
8989

90-
* `QName:`StreamUniquenessManager` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/util.py`, Lines:(1:1000) <https://github.com/CodeBoarding/praw/blob/main/.codeboarding/praw/models/util.py#L1-L1000>`_
90+
* `StreamUniquenessManager:1-1000 <https://github.com/praw-dev/praw/blob/main/praw/models/util.py#L1-L1000>`_
9191

9292
StreamBackoffHandler
9393
^^^^^^^^^^^^^^^^^^^^
@@ -96,7 +96,7 @@ Implements an exponential backoff strategy to manage delays between stream reque
9696

9797
**Related Classes/Methods**:
9898

99-
* `QName:`StreamBackoffHandler` FileRef: `/home/ubuntu/CodeBoarding/repo/praw/praw/models/util.py`, Lines:(1:1000) <https://github.com/CodeBoarding/praw/blob/main/.codeboarding/praw/models/util.py#L1-L1000>`_
99+
* `StreamBackoffHandler:1-1000 <https://github.com/praw-dev/praw/blob/main/praw/models/util.py#L1-L1000>`_
100100

101101

102102
FAQ

0 commit comments

Comments
 (0)