Skip to content

Commit ca26447

Browse files
ivanmilevtuesivanmilevtues
committed
Updates on the github action and adding the results to the docs
1 parent 55a62c2 commit ca26447

File tree

10 files changed

+661
-1
lines changed

10 files changed

+661
-1
lines changed

‎.github/workflows/docs_codeboarding.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,34 @@ jobs:
8787
echo "JSON directory: ${{ steps.codeboarding.outputs.json_directory }}"
8888
echo "Has changes: ${{ steps.codeboarding.outputs.has_changes }}"
8989
90+
# Move .rst files from docs/architecture_overview/ to .codeboarding folder
91+
- name: Move architecture overview .rst files
92+
run: |
93+
# Create .codeboarding directory if it doesn't exist
94+
mkdir -p .codeboarding
95+
96+
# Check if docs/architecture_overview/ exists and contains .rst files
97+
if [ -d "docs/architecture_overview" ] && [ -n "$(find docs/architecture_overview -name '*.rst' -type f)" ]; then
98+
echo "Moving .rst files from docs/architecture_overview/ to .codeboarding/"
99+
100+
# Copy .rst files to .codeboarding folder
101+
cp docs/architecture_overview/*.rst .codeboarding/ 2>/dev/null || echo "No .rst files found to copy"
102+
103+
# Also copy any subdirectories with .rst files
104+
find docs/architecture_overview -type d -exec sh -c '
105+
for dir do
106+
if [ -n "$(find "$dir" -maxdepth 1 -name "*.rst" -type f)" ]; then
107+
echo "Copying .rst files from $dir"
108+
cp "$dir"/*.rst .codeboarding/ 2>/dev/null || echo "No .rst files found in $dir"
109+
fi
110+
done
111+
' sh {} +
112+
113+
echo "Architecture overview .rst files moved successfully"
114+
else
115+
echo "No docs/architecture_overview/ directory or .rst files found"
116+
fi
117+
90118
# Check if we have any changes to commit
91119
- name: Check for changes
92120
id: git-changes

‎docs/architecture_overview/API_Client_Core.rst‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
Api Client Core
2+
===============
3+
4+
.. mermaid::
5+
6+
graph LR
7+
API_Client_Core["API Client Core"]
8+
Client_Initializer["Client Initializer"]
9+
Request_Executor["Request Executor"]
10+
Response_Objectifier["Response Objectifier"]
11+
Rate_Limit_Manager["Rate Limit Manager"]
12+
API_Operation_Methods["API Operation Methods"]
13+
Async_Checker["Async Checker"]
14+
Client_Initializer -- "initializes" --> API_Client_Core
15+
API_Client_Core -- "manages" --> Request_Executor
16+
API_Client_Core -- "manages" --> Response_Objectifier
17+
API_Client_Core -- "manages" --> Rate_Limit_Manager
18+
API_Client_Core -- "exposes" --> API_Operation_Methods
19+
API_Operation_Methods -- "invokes" --> Request_Executor
20+
Request_Executor -- "checks" --> Async_Checker
21+
Request_Executor -- "returns raw response to" --> Response_Objectifier
22+
Response_Objectifier -- "transforms for" --> API_Operation_Methods
23+
API_Operation_Methods -- "consults" --> Rate_Limit_Manager
24+
click API_Client_Core href "https://github.com/praw-dev/praw/blob/main/.codeboarding/API_Client_Core.html" "Details"
25+
26+
| |codeboarding-badge| |demo-badge| |contact-badge|
27+
28+
.. |codeboarding-badge| image:: https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square
29+
:target: https://github.com/CodeBoarding/CodeBoarding
30+
.. |demo-badge| image:: https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square
31+
:target: https://www.codeboarding.org/demo
32+
.. |contact-badge| image:: https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square
33+
:target: mailto:contact@codeboarding.org
34+
35+
Details
36+
-------
37+
38+
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.
39+
40+
API Client Core
41+
^^^^^^^^^^^^^^^
42+
43+
:ref:`Expand <API_Client_Core>`
44+
45+
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.
46+
47+
**Related Classes/Methods**:
48+
49+
* `praw.reddit.Reddit:57-901 <https://github.com/praw-dev/praw/blob/main/praw/reddit.py#L57-L901>`_
50+
51+
Client Initializer
52+
^^^^^^^^^^^^^^^^^^
53+
54+
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.
55+
56+
**Related Classes/Methods**:
57+
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>`_
61+
62+
Request Executor
63+
^^^^^^^^^^^^^^^^
64+
65+
Executes the raw HTTP requests to the Reddit API, handling the low-level communication details.
66+
67+
**Related Classes/Methods**:
68+
69+
* `praw.reddit.Reddit.request <https://github.com/praw-dev/praw/blob/main/praw/reddit.py>`_
70+
71+
Response Objectifier
72+
^^^^^^^^^^^^^^^^^^^^
73+
74+
Transforms the raw JSON responses from the API into structured PRAW Python objects, making them easier to consume and work with.
75+
76+
**Related Classes/Methods**:
77+
78+
* `praw.reddit.Reddit._objectify_request <https://github.com/praw-dev/praw/blob/main/praw/reddit.py>`_
79+
80+
Rate Limit Manager
81+
^^^^^^^^^^^^^^^^^^
82+
83+
Monitors and enforces Reddit's API rate limits, pausing requests when necessary to prevent exceeding usage quotas and ensuring compliance.
84+
85+
**Related Classes/Methods**:
86+
87+
* `praw.reddit.Reddit._handle_rate_limit <https://github.com/praw-dev/praw/blob/main/praw/reddit.py>`_
88+
89+
API Operation Methods
90+
^^^^^^^^^^^^^^^^^^^^^
91+
92+
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.
93+
94+
**Related Classes/Methods**:
95+
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>`_
101+
102+
Async Checker
103+
^^^^^^^^^^^^^
104+
105+
Manages and verifies the asynchronous context for operations, ensuring proper execution in async environments.
106+
107+
**Related Classes/Methods**:
108+
109+
* `praw.reddit._check_for_async:388-411 <https://github.com/praw-dev/praw/blob/main/praw/reddit.py#L388-L411>`_
110+
111+
112+
FAQ
113+
---
114+
115+
`See the FAQ <https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq>`_

‎docs/architecture_overview/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>`_

‎docs/architecture_overview/Listing_Stream_Processors.rst‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
Listing Stream Processors
2+
=========================
3+
4+
.. mermaid::
5+
6+
graph LR
7+
ListingGenerator["ListingGenerator"]
8+
ListingBatchFetcher["ListingBatchFetcher"]
9+
ListingDataExtractor["ListingDataExtractor"]
10+
ListingParameterMixin["ListingParameterMixin"]
11+
StreamProcessor["StreamProcessor"]
12+
StreamUniquenessManager["StreamUniquenessManager"]
13+
StreamBackoffHandler["StreamBackoffHandler"]
14+
ListingGenerator -- "initiates data retrieval by calling" --> ListingBatchFetcher
15+
ListingBatchFetcher -- "fetches data and returns it to" --> ListingGenerator
16+
ListingBatchFetcher -- "invokes" --> ListingDataExtractor
17+
ListingDataExtractor -- "provides the extracted list of items back to" --> ListingBatchFetcher
18+
ListingParameterMixin -- "is utilized by" --> ListingBatchFetcher
19+
StreamProcessor -- "utilizes" --> StreamUniquenessManager
20+
StreamUniquenessManager -- "provides uniqueness checks for" --> StreamProcessor
21+
StreamProcessor -- "consults" --> StreamBackoffHandler
22+
StreamBackoffHandler -- "provides backoff durations to" --> StreamProcessor
23+
24+
| |codeboarding-badge| |demo-badge| |contact-badge|
25+
26+
.. |codeboarding-badge| image:: https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square
27+
:target: https://github.com/CodeBoarding/CodeBoarding
28+
.. |demo-badge| image:: https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square
29+
:target: https://www.codeboarding.org/demo
30+
.. |contact-badge| image:: https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square
31+
:target: mailto:contact@codeboarding.org
32+
33+
Details
34+
-------
35+
36+
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.
37+
38+
ListingGenerator
39+
^^^^^^^^^^^^^^^^
40+
41+
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.
42+
43+
**Related Classes/Methods**:
44+
45+
* `ListingGenerator:17-103 <https://github.com/praw-dev/praw/blob/main/praw/models/listing/generator.py#L17-L103>`_
46+
47+
ListingBatchFetcher
48+
^^^^^^^^^^^^^^^^^^^
49+
50+
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.
51+
52+
**Related Classes/Methods**:
53+
54+
* `ListingBatchFetcher:1-1000 <https://github.com/praw-dev/praw/blob/main/praw/models/listing/generator.py#L1-L1000>`_
55+
56+
ListingDataExtractor
57+
^^^^^^^^^^^^^^^^^^^^
58+
59+
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.
60+
61+
**Related Classes/Methods**:
62+
63+
* `ListingDataExtractor:1-1000 <https://github.com/praw-dev/praw/blob/main/praw/models/listing/generator.py#L1-L1000>`_
64+
65+
ListingParameterMixin
66+
^^^^^^^^^^^^^^^^^^^^^
67+
68+
Provides common methods for constructing API paths and parameters required for various types of listings. This ensures consistency and reusability across different listing endpoints.
69+
70+
**Related Classes/Methods**:
71+
72+
* `ListingParameterMixin:1-1000 <https://github.com/praw-dev/praw/blob/main/praw/models/listing/mixins/base.py#L1-L1000>`_
73+
74+
StreamProcessor
75+
^^^^^^^^^^^^^^^
76+
77+
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.
78+
79+
**Related Classes/Methods**:
80+
81+
* `StreamProcessor:1-1000 <https://github.com/praw-dev/praw/blob/main/praw/models/util.py#L1-L1000>`_
82+
83+
StreamUniquenessManager
84+
^^^^^^^^^^^^^^^^^^^^^^^
85+
86+
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.
87+
88+
**Related Classes/Methods**:
89+
90+
* `StreamUniquenessManager:1-1000 <https://github.com/praw-dev/praw/blob/main/praw/models/util.py#L1-L1000>`_
91+
92+
StreamBackoffHandler
93+
^^^^^^^^^^^^^^^^^^^^
94+
95+
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.
96+
97+
**Related Classes/Methods**:
98+
99+
* `StreamBackoffHandler:1-1000 <https://github.com/praw-dev/praw/blob/main/praw/models/util.py#L1-L1000>`_
100+
101+
102+
FAQ
103+
---
104+
105+
`See the FAQ <https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq>`_

0 commit comments

Comments
 (0)