jopedro-core-lib 0.1.0b1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. jopedro_core_lib-0.1.0b1/PKG-INFO +226 -0
  2. jopedro_core_lib-0.1.0b1/README.md +208 -0
  3. jopedro_core_lib-0.1.0b1/core_lib/__init__.py +1 -0
  4. jopedro_core_lib-0.1.0b1/core_lib/discord/__init__.py +13 -0
  5. jopedro_core_lib-0.1.0b1/core_lib/discord/discord_service.py +135 -0
  6. jopedro_core_lib-0.1.0b1/core_lib/file_utils/__init__.py +1 -0
  7. jopedro_core_lib-0.1.0b1/core_lib/file_utils/file_utils.py +29 -0
  8. jopedro_core_lib-0.1.0b1/core_lib/gdrive/__init__.py +16 -0
  9. jopedro_core_lib-0.1.0b1/core_lib/gdrive/gdrive_auth.py +64 -0
  10. jopedro_core_lib-0.1.0b1/core_lib/gdrive/gdrive_helpers.py +49 -0
  11. jopedro_core_lib-0.1.0b1/core_lib/gdrive/gdrive_service.py +331 -0
  12. jopedro_core_lib-0.1.0b1/core_lib/logger/__init__.py +2 -0
  13. jopedro_core_lib-0.1.0b1/core_lib/logger/logger.py +63 -0
  14. jopedro_core_lib-0.1.0b1/jopedro_core_lib.egg-info/PKG-INFO +226 -0
  15. jopedro_core_lib-0.1.0b1/jopedro_core_lib.egg-info/SOURCES.txt +25 -0
  16. jopedro_core_lib-0.1.0b1/jopedro_core_lib.egg-info/dependency_links.txt +1 -0
  17. jopedro_core_lib-0.1.0b1/jopedro_core_lib.egg-info/requires.txt +14 -0
  18. jopedro_core_lib-0.1.0b1/jopedro_core_lib.egg-info/top_level.txt +1 -0
  19. jopedro_core_lib-0.1.0b1/pyproject.toml +49 -0
  20. jopedro_core_lib-0.1.0b1/setup.cfg +4 -0
  21. jopedro_core_lib-0.1.0b1/tests/test_discord_service.py +115 -0
  22. jopedro_core_lib-0.1.0b1/tests/test_file_utils.py +34 -0
  23. jopedro_core_lib-0.1.0b1/tests/test_gdrive_auth.py +58 -0
  24. jopedro_core_lib-0.1.0b1/tests/test_gdrive_helpers.py +32 -0
  25. jopedro_core_lib-0.1.0b1/tests/test_gdrive_service.py +195 -0
  26. jopedro_core_lib-0.1.0b1/tests/test_gdrive_update_bot.py +232 -0
  27. jopedro_core_lib-0.1.0b1/tests/test_logger.py +83 -0
@@ -0,0 +1,226 @@
1
+ Metadata-Version: 2.4
2
+ Name: jopedro-core-lib
3
+ Version: 0.1.0b1
4
+ Summary: Shared support library
5
+ Requires-Python: >=3.10
6
+ Description-Content-Type: text/markdown
7
+ Provides-Extra: discord
8
+ Requires-Dist: requests>=2.28; extra == "discord"
9
+ Provides-Extra: gdrive
10
+ Requires-Dist: google-auth>=2.0; extra == "gdrive"
11
+ Requires-Dist: google-auth-oauthlib>=1.0; extra == "gdrive"
12
+ Requires-Dist: google-api-python-client>=2.0; extra == "gdrive"
13
+ Provides-Extra: dev
14
+ Requires-Dist: pytest>=7; extra == "dev"
15
+ Requires-Dist: ruff>=0.4; extra == "dev"
16
+ Requires-Dist: mypy>=1.10; extra == "dev"
17
+ Requires-Dist: types-requests>=2.28; extra == "dev"
18
+
19
+ # core-lib
20
+
21
+ ![Python 3.10+](https://img.shields.io/badge/python-3.10+-3776AB?style=flat-square&logo=python&logoColor=white)
22
+ ![Version](https://img.shields.io/badge/version-0.1.0-58a6ff?style=flat-square)
23
+ ![CI](https://github.com/jopedro-labs/core-lib/actions/workflows/ci.yml/badge.svg?branch=main)
24
+ ![Monitor GDrive API](https://github.com/jopedro-labs/core-lib/actions/workflows/gdrive_bot.yml/badge.svg)
25
+ <br />
26
+ ![Linter](https://img.shields.io/badge/linter-Ruff-000000?style=flat-square&logo=python&logoColor=white)
27
+ ![Type Check](https://img.shields.io/badge/types-mypy%20strict-2A6DB2?style=flat-square&logo=python&logoColor=white)
28
+ ![Pytest](https://img.shields.io/badge/Pytest-0A9EDC?style=flat-square&logo=pytest&logoColor=white)
29
+ ![Gemini AI](https://img.shields.io/badge/Gemini_AI-8E75B2?style=flat-square&logo=googlegemini&logoColor=white)
30
+ ![GNU Make](https://img.shields.io/badge/env-GNU%20Make-active?style=flat-square&logo=gnu-make&logoColor=white)
31
+ ![MIT License](https://img.shields.io/badge/license-MIT-607D8B?style=flat-square)
32
+
33
+ Shared Python support library. Provides common utilities (logging, file I/O), service integrations, and autonomous code quality evaluation tools for internal projects.
34
+
35
+ ---
36
+
37
+ ## Installation
38
+
39
+ Add to your project's `requirements.txt` / `pyproject.toml` via Git reference:
40
+
41
+ ```text
42
+ core-lib @ git+https://github.com/jopedro-labs/core-lib.git@v0.1.0
43
+ ```
44
+
45
+ ---
46
+
47
+ ## Modules & Tools
48
+
49
+ ### `core_lib.logger`
50
+
51
+ ANSI-colored terminal logger. Outputs to stdout (or stderr for errors) with timestamps. No file persistence.
52
+
53
+ ```python
54
+ from core_lib.logger import logger
55
+
56
+ logger.info("Starting job")
57
+ logger.success("Job completed")
58
+ logger.warning("Retrying...")
59
+ logger.error("Something failed", exception=ValueError("details"))
60
+ logger.section("Phase 1") # bold header
61
+ logger.subsection("Step 1.1") # bold subheader
62
+ logger.print("raw output")
63
+ ```
64
+
65
+ You can also instantiate `Logger` directly if you need an isolated instance:
66
+
67
+ ```python
68
+ from core_lib.logger import Logger
69
+
70
+ my_logger = Logger()
71
+ ```
72
+
73
+ ### `core_lib.file_utils`
74
+
75
+ Safe file reading utilities. Always returns a string — never raises.
76
+
77
+ ```python
78
+ from core_lib.file_utils import load_file_content
79
+
80
+ content = load_file_content("/path/to/file.txt") # "" if missing or unreadable
81
+ ```
82
+
83
+ ---
84
+
85
+ ### `core_lib.gdrive`
86
+
87
+ Google Drive client using OAuth2 and the **Google Drive API v3**. Requires the `[gdrive]` extra.
88
+
89
+ **Underlying API & Dependencies:**
90
+ * **API Version:** Google Drive API v3 (`https://www.googleapis.com/discovery/v1/apis/drive/v3/rest`)
91
+ * **Python Client Library:** `google-api-python-client >= 2.0`
92
+ * **Authentication:** `google-auth >= 2.0`, `google-auth-oauthlib >= 1.0`
93
+ * **Scopes:** `https://www.googleapis.com/auth/drive.file`
94
+
95
+ **Automated API Monitoring (GDrive Update Bot):**
96
+ * **Schedule:** Runs automatically every Thursday at 08:00 UTC (and supports manual workflow dispatch).
97
+ * **Mechanism:** Queries Google's public Discovery Service using standard libraries (`scripts/gdrive_update_bot.py`) with built-in retry logic and linear backoff.
98
+ * **Resilience & Alerts:** Persists revision states locally (`.github/api-revisions/gdrive-revision.json`), committing updates on success and opening targeted GitHub Issues if a breaking API revision change or network failure occurs. Can also be run manually: `python scripts/gdrive_update_bot.py`.
99
+
100
+ **Environment variables (optional — can be overridden per instance):**
101
+
102
+ | Variable | Default | Description |
103
+ |---------------------------|--------------------|-------------------------------------|
104
+ | `GDRIVE_CREDENTIALS_PATH` | `credentials.json` | Path to the OAuth2 credentials file |
105
+ | `GDRIVE_TOKEN_PATH` | `token.json` | Path to the token file |
106
+ | `GDRIVE_DATA_FOLDER_ID` | `None` | Default target folder ID |
107
+
108
+ ```python
109
+ from core_lib.gdrive import GDriveService, sanitize_gdrive_folder_id
110
+
111
+ # uses env vars or defaults
112
+ drive = GDriveService()
113
+
114
+ # or inject explicitly
115
+ drive = GDriveService(
116
+ credentials_path="/secrets/credentials.json",
117
+ token_path="/secrets/token.json",
118
+ folder_id="1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs",
119
+ )
120
+
121
+ drive.verify_folder_access()
122
+ drive.upload_file("report.csv", overwrite=True)
123
+ drive.download_file("report.csv", destination_path="/tmp/report.csv")
124
+ drive.list_files()
125
+ drive.backup_file("data.db")
126
+ drive.sync_files(["a.csv", "b.csv"], direction="push")
127
+ drive.get_latest_file_id(prefix="finances")
128
+ drive.download_latest_file(destination_path="finances.db", prefix="finances")
129
+ drive.get_file_modified_time("xtb_screenshot.png")
130
+ ```
131
+
132
+ ---
133
+
134
+ ### `core_lib.discord`
135
+
136
+ Discord notification client supporting both Bot API (with dynamic channel targeting) and Webhook URLs. Requires the `[discord]` extra.
137
+
138
+ **Features:**
139
+ * **Dynamic Channel Targeting:** Send messages or embeds to specific channels dynamically using a Discord Bot Token (`channel_id` argument)
140
+ * **Webhook Fallback:** Support for traditional fixed-channel Webhook URLs
141
+ * **Rate-Limit Awareness:** Explicit handling of HTTP 429 responses with `retry_after` extraction
142
+ * **Context Manager Support:** Clean resource management using `with` statements
143
+
144
+ ```python
145
+ from core_lib.discord import DiscordNotifier, DiscordNotificationError
146
+
147
+ # Using a Bot Token for dynamic channel targeting
148
+ try:
149
+ with DiscordNotifier(bot_token="YOUR_BOT_TOKEN") as notifier:
150
+ notifier.send_message(
151
+ content="🚨 **Alert**: Automated job completed successfully.",
152
+ channel_id="123456789012345678"
153
+ )
154
+ except DiscordNotificationError as e:
155
+ print(f"Failed to notify: {e}")
156
+
157
+ # Using a traditional Webhook URL
158
+ notifier = DiscordNotifier(webhook_url="https://discord.com/api/webhooks/...")
159
+ notifier.send_message(content="Hello from core-lib!")
160
+ notifier.close()
161
+ ```
162
+
163
+ ---
164
+
165
+ ### Autonomous Quality Assurance & Test Gap Evaluation Agent
166
+
167
+ An internal developer utility (`scripts/quality_eval_agent.py`) powered by Gemini AI that acts as an autonomous quality assurance auditor within the repository.
168
+
169
+ **Core Validation Pillars Evaluated:**
170
+ 1. **Unit Tests:** Isolated verification and mocking via `pytest`.
171
+ 2. **Integration Tests:** Component and adapter interaction verification.
172
+ 3. **Static Code Analysis:** Type safety (`mypy`) and linting (`ruff`).
173
+ 4. **Mutation Testing Readiness:** Assessment of test suite robustness against code changes.
174
+ 5. **Black-Box Verification:** Functional and behavioral validation.
175
+
176
+ **Execution:**
177
+ ```bash
178
+ make quality-eval-agent
179
+ ```
180
+
181
+ The agent automatically executes the test suite with coverage, gathers repository context, analyzes coverage gaps and validation metrics via the configured Gemini model (`GEMINI_MODEL`), and generates a structured markdown report under `reports/validation_gap_report.md`.
182
+
183
+ ---
184
+
185
+ ## Requirements
186
+
187
+ - Python >= 3.10
188
+ - Core utilities (logging, file I/O): No external dependencies.
189
+ - Google Drive extra (`[gdrive]`): Requires Google API client libraries (`google-api-python-client`, `google-auth`, `google-auth-oauthlib`).
190
+ - Discord extra (`[discord]`): Requires `requests`.
191
+ - Quality Evaluation Agent: Requires `google-generativeai` (or `google.genai`), `python-dotenv`, and an active `GEMINI_API_KEY`.
192
+ ---
193
+
194
+ ## Development
195
+
196
+ ```bash
197
+ git clone https://github.com/jopedro-labs/core-lib.git
198
+ cd core-lib
199
+ make install
200
+ ```
201
+
202
+ Run all checks (lint, types, tests):
203
+
204
+ ```bash
205
+ make check
206
+ ```
207
+
208
+ Individual commands:
209
+
210
+ | Command | Description |
211
+ |---------------------------|------------------------------------------|
212
+ | `make lint` | Lint with ruff |
213
+ | `make type` | Type check with mypy |
214
+ | `make test` | Run tests with pytest |
215
+ | `make quality-eval-agent` | Run AI quality audit & test gap analysis |
216
+ | `make check` | Run all three in sequence |
217
+
218
+ ---
219
+
220
+ ## License
221
+
222
+ Distributed under the MIT License.
223
+
224
+ Developed and maintained by **João Pedro** ([@JoPedro15](https://github.com/JoPedro15)).
225
+
226
+ > *Fueled by Espresso, CrossFit WODs, and powered by Gemini AI.* ☕🏋️‍♂️🤖
@@ -0,0 +1,208 @@
1
+ # core-lib
2
+
3
+ ![Python 3.10+](https://img.shields.io/badge/python-3.10+-3776AB?style=flat-square&logo=python&logoColor=white)
4
+ ![Version](https://img.shields.io/badge/version-0.1.0-58a6ff?style=flat-square)
5
+ ![CI](https://github.com/jopedro-labs/core-lib/actions/workflows/ci.yml/badge.svg?branch=main)
6
+ ![Monitor GDrive API](https://github.com/jopedro-labs/core-lib/actions/workflows/gdrive_bot.yml/badge.svg)
7
+ <br />
8
+ ![Linter](https://img.shields.io/badge/linter-Ruff-000000?style=flat-square&logo=python&logoColor=white)
9
+ ![Type Check](https://img.shields.io/badge/types-mypy%20strict-2A6DB2?style=flat-square&logo=python&logoColor=white)
10
+ ![Pytest](https://img.shields.io/badge/Pytest-0A9EDC?style=flat-square&logo=pytest&logoColor=white)
11
+ ![Gemini AI](https://img.shields.io/badge/Gemini_AI-8E75B2?style=flat-square&logo=googlegemini&logoColor=white)
12
+ ![GNU Make](https://img.shields.io/badge/env-GNU%20Make-active?style=flat-square&logo=gnu-make&logoColor=white)
13
+ ![MIT License](https://img.shields.io/badge/license-MIT-607D8B?style=flat-square)
14
+
15
+ Shared Python support library. Provides common utilities (logging, file I/O), service integrations, and autonomous code quality evaluation tools for internal projects.
16
+
17
+ ---
18
+
19
+ ## Installation
20
+
21
+ Add to your project's `requirements.txt` / `pyproject.toml` via Git reference:
22
+
23
+ ```text
24
+ core-lib @ git+https://github.com/jopedro-labs/core-lib.git@v0.1.0
25
+ ```
26
+
27
+ ---
28
+
29
+ ## Modules & Tools
30
+
31
+ ### `core_lib.logger`
32
+
33
+ ANSI-colored terminal logger. Outputs to stdout (or stderr for errors) with timestamps. No file persistence.
34
+
35
+ ```python
36
+ from core_lib.logger import logger
37
+
38
+ logger.info("Starting job")
39
+ logger.success("Job completed")
40
+ logger.warning("Retrying...")
41
+ logger.error("Something failed", exception=ValueError("details"))
42
+ logger.section("Phase 1") # bold header
43
+ logger.subsection("Step 1.1") # bold subheader
44
+ logger.print("raw output")
45
+ ```
46
+
47
+ You can also instantiate `Logger` directly if you need an isolated instance:
48
+
49
+ ```python
50
+ from core_lib.logger import Logger
51
+
52
+ my_logger = Logger()
53
+ ```
54
+
55
+ ### `core_lib.file_utils`
56
+
57
+ Safe file reading utilities. Always returns a string — never raises.
58
+
59
+ ```python
60
+ from core_lib.file_utils import load_file_content
61
+
62
+ content = load_file_content("/path/to/file.txt") # "" if missing or unreadable
63
+ ```
64
+
65
+ ---
66
+
67
+ ### `core_lib.gdrive`
68
+
69
+ Google Drive client using OAuth2 and the **Google Drive API v3**. Requires the `[gdrive]` extra.
70
+
71
+ **Underlying API & Dependencies:**
72
+ * **API Version:** Google Drive API v3 (`https://www.googleapis.com/discovery/v1/apis/drive/v3/rest`)
73
+ * **Python Client Library:** `google-api-python-client >= 2.0`
74
+ * **Authentication:** `google-auth >= 2.0`, `google-auth-oauthlib >= 1.0`
75
+ * **Scopes:** `https://www.googleapis.com/auth/drive.file`
76
+
77
+ **Automated API Monitoring (GDrive Update Bot):**
78
+ * **Schedule:** Runs automatically every Thursday at 08:00 UTC (and supports manual workflow dispatch).
79
+ * **Mechanism:** Queries Google's public Discovery Service using standard libraries (`scripts/gdrive_update_bot.py`) with built-in retry logic and linear backoff.
80
+ * **Resilience & Alerts:** Persists revision states locally (`.github/api-revisions/gdrive-revision.json`), committing updates on success and opening targeted GitHub Issues if a breaking API revision change or network failure occurs. Can also be run manually: `python scripts/gdrive_update_bot.py`.
81
+
82
+ **Environment variables (optional — can be overridden per instance):**
83
+
84
+ | Variable | Default | Description |
85
+ |---------------------------|--------------------|-------------------------------------|
86
+ | `GDRIVE_CREDENTIALS_PATH` | `credentials.json` | Path to the OAuth2 credentials file |
87
+ | `GDRIVE_TOKEN_PATH` | `token.json` | Path to the token file |
88
+ | `GDRIVE_DATA_FOLDER_ID` | `None` | Default target folder ID |
89
+
90
+ ```python
91
+ from core_lib.gdrive import GDriveService, sanitize_gdrive_folder_id
92
+
93
+ # uses env vars or defaults
94
+ drive = GDriveService()
95
+
96
+ # or inject explicitly
97
+ drive = GDriveService(
98
+ credentials_path="/secrets/credentials.json",
99
+ token_path="/secrets/token.json",
100
+ folder_id="1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs",
101
+ )
102
+
103
+ drive.verify_folder_access()
104
+ drive.upload_file("report.csv", overwrite=True)
105
+ drive.download_file("report.csv", destination_path="/tmp/report.csv")
106
+ drive.list_files()
107
+ drive.backup_file("data.db")
108
+ drive.sync_files(["a.csv", "b.csv"], direction="push")
109
+ drive.get_latest_file_id(prefix="finances")
110
+ drive.download_latest_file(destination_path="finances.db", prefix="finances")
111
+ drive.get_file_modified_time("xtb_screenshot.png")
112
+ ```
113
+
114
+ ---
115
+
116
+ ### `core_lib.discord`
117
+
118
+ Discord notification client supporting both Bot API (with dynamic channel targeting) and Webhook URLs. Requires the `[discord]` extra.
119
+
120
+ **Features:**
121
+ * **Dynamic Channel Targeting:** Send messages or embeds to specific channels dynamically using a Discord Bot Token (`channel_id` argument)
122
+ * **Webhook Fallback:** Support for traditional fixed-channel Webhook URLs
123
+ * **Rate-Limit Awareness:** Explicit handling of HTTP 429 responses with `retry_after` extraction
124
+ * **Context Manager Support:** Clean resource management using `with` statements
125
+
126
+ ```python
127
+ from core_lib.discord import DiscordNotifier, DiscordNotificationError
128
+
129
+ # Using a Bot Token for dynamic channel targeting
130
+ try:
131
+ with DiscordNotifier(bot_token="YOUR_BOT_TOKEN") as notifier:
132
+ notifier.send_message(
133
+ content="🚨 **Alert**: Automated job completed successfully.",
134
+ channel_id="123456789012345678"
135
+ )
136
+ except DiscordNotificationError as e:
137
+ print(f"Failed to notify: {e}")
138
+
139
+ # Using a traditional Webhook URL
140
+ notifier = DiscordNotifier(webhook_url="https://discord.com/api/webhooks/...")
141
+ notifier.send_message(content="Hello from core-lib!")
142
+ notifier.close()
143
+ ```
144
+
145
+ ---
146
+
147
+ ### Autonomous Quality Assurance & Test Gap Evaluation Agent
148
+
149
+ An internal developer utility (`scripts/quality_eval_agent.py`) powered by Gemini AI that acts as an autonomous quality assurance auditor within the repository.
150
+
151
+ **Core Validation Pillars Evaluated:**
152
+ 1. **Unit Tests:** Isolated verification and mocking via `pytest`.
153
+ 2. **Integration Tests:** Component and adapter interaction verification.
154
+ 3. **Static Code Analysis:** Type safety (`mypy`) and linting (`ruff`).
155
+ 4. **Mutation Testing Readiness:** Assessment of test suite robustness against code changes.
156
+ 5. **Black-Box Verification:** Functional and behavioral validation.
157
+
158
+ **Execution:**
159
+ ```bash
160
+ make quality-eval-agent
161
+ ```
162
+
163
+ The agent automatically executes the test suite with coverage, gathers repository context, analyzes coverage gaps and validation metrics via the configured Gemini model (`GEMINI_MODEL`), and generates a structured markdown report under `reports/validation_gap_report.md`.
164
+
165
+ ---
166
+
167
+ ## Requirements
168
+
169
+ - Python >= 3.10
170
+ - Core utilities (logging, file I/O): No external dependencies.
171
+ - Google Drive extra (`[gdrive]`): Requires Google API client libraries (`google-api-python-client`, `google-auth`, `google-auth-oauthlib`).
172
+ - Discord extra (`[discord]`): Requires `requests`.
173
+ - Quality Evaluation Agent: Requires `google-generativeai` (or `google.genai`), `python-dotenv`, and an active `GEMINI_API_KEY`.
174
+ ---
175
+
176
+ ## Development
177
+
178
+ ```bash
179
+ git clone https://github.com/jopedro-labs/core-lib.git
180
+ cd core-lib
181
+ make install
182
+ ```
183
+
184
+ Run all checks (lint, types, tests):
185
+
186
+ ```bash
187
+ make check
188
+ ```
189
+
190
+ Individual commands:
191
+
192
+ | Command | Description |
193
+ |---------------------------|------------------------------------------|
194
+ | `make lint` | Lint with ruff |
195
+ | `make type` | Type check with mypy |
196
+ | `make test` | Run tests with pytest |
197
+ | `make quality-eval-agent` | Run AI quality audit & test gap analysis |
198
+ | `make check` | Run all three in sequence |
199
+
200
+ ---
201
+
202
+ ## License
203
+
204
+ Distributed under the MIT License.
205
+
206
+ Developed and maintained by **João Pedro** ([@JoPedro15](https://github.com/JoPedro15)).
207
+
208
+ > *Fueled by Espresso, CrossFit WODs, and powered by Gemini AI.* ☕🏋️‍♂️🤖
@@ -0,0 +1 @@
1
+ __version__ = "0.1.0"
@@ -0,0 +1,13 @@
1
+ """Discord notification submodule — bot API and webhook support."""
2
+
3
+ from __future__ import annotations
4
+
5
+
6
+ def __getattr__(name: str) -> object:
7
+ if name == "DiscordNotifier":
8
+ from core_lib.discord.discord_service import DiscordNotifier
9
+ return DiscordNotifier
10
+ if name == "DiscordNotificationError":
11
+ from core_lib.discord.discord_service import DiscordNotificationError
12
+ return DiscordNotificationError
13
+ raise AttributeError(f"module 'core_lib.discord' has no attribute {name!r}")
@@ -0,0 +1,135 @@
1
+ """
2
+ Discord notification client supporting both Bot API (with dynamic channel targeting)
3
+ and Webhook URLs.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ import logging
9
+ from typing import Any
10
+
11
+ import requests
12
+ from requests.adapters import HTTPAdapter
13
+ from urllib3.util import Retry
14
+
15
+ logger = logging.getLogger(__name__)
16
+
17
+
18
+ class DiscordNotificationError(Exception):
19
+ """Raised when failing to send a notification to Discord."""
20
+
21
+ pass
22
+
23
+
24
+ class DiscordNotifier:
25
+ """Client for dispatching notifications to Discord channels."""
26
+
27
+ API_BASE_URL: str = "https://discord.com/api/v10"
28
+
29
+ def __init__(
30
+ self,
31
+ bot_token: str | None = None,
32
+ webhook_url: str | None = None,
33
+ timeout: float = 10.0,
34
+ max_retries: int = 3,
35
+ ) -> None:
36
+ """Initializes the Discord notifier.
37
+
38
+ Args:
39
+ bot_token: Discord Bot Token for dynamic channel targeting.
40
+ webhook_url: Fallback webhook URL for fixed-channel broadcasting.
41
+ timeout: Request timeout in seconds.
42
+ max_retries: Maximum number of HTTP retry attempts.
43
+ """
44
+ if not bot_token and not webhook_url:
45
+ raise ValueError(
46
+ "[discord] Either 'bot_token' or 'webhook_url' must be provided."
47
+ )
48
+
49
+ self.bot_token: str | None = bot_token
50
+ self.webhook_url: str | None = webhook_url
51
+ self.timeout: float = timeout
52
+
53
+ self.session: requests.Session = requests.Session()
54
+ retries: Retry = Retry(
55
+ total=max_retries,
56
+ backoff_factor=1.0,
57
+ # 429 intentionally excluded: Discord returns retry_after in the body,
58
+ # so callers should handle rate-limit responses explicitly rather than
59
+ # relying on blind exponential back-off that ignores that value.
60
+ status_forcelist=[500, 502, 503, 504],
61
+ raise_on_status=False,
62
+ )
63
+ adapter: HTTPAdapter = HTTPAdapter(max_retries=retries)
64
+ self.session.mount("https://", adapter)
65
+ self.session.mount("http://", adapter)
66
+
67
+ def send_message(
68
+ self,
69
+ content: str | None = None,
70
+ channel_id: str | None = None,
71
+ embeds: list[dict[str, Any]] | None = None,
72
+ ) -> None:
73
+ """Send a text message or rich embeds to Discord via Bot API or Webhook.
74
+
75
+ Args:
76
+ content: The text content of the message.
77
+ channel_id: Optional target channel ID (required for Bot token mode).
78
+ embeds: Optional list of rich embed dictionaries.
79
+
80
+ Raises:
81
+ ValueError: If neither content nor embeds are provided, or if channel_id
82
+ is missing when using a bot token.
83
+ DiscordNotificationError: If the API request fails or is rate-limited.
84
+ """
85
+ if not content and not embeds:
86
+ raise ValueError("Either 'content' or at least one embed is required.")
87
+
88
+ if self.bot_token and not channel_id:
89
+ raise ValueError("'channel_id' is required when using a bot token.")
90
+
91
+ payload: dict[str, Any] = {}
92
+ if content:
93
+ payload["content"] = content
94
+ if embeds:
95
+ payload["embeds"] = embeds
96
+
97
+ if self.bot_token:
98
+ url = f"https://discord.com/api/v10/channels/{channel_id}/messages"
99
+ headers = {
100
+ "Content-Type": "application/json",
101
+ "Authorization": f"Bot {self.bot_token}",
102
+ }
103
+ else:
104
+ url = str(self.webhook_url)
105
+ headers = {"Content-Type": "application/json"}
106
+
107
+ try:
108
+ response = self.session.post(url, json=payload, headers=headers, timeout=self.timeout)
109
+
110
+ if response.status_code == 429:
111
+ data = response.json() if response.content else {}
112
+ retry_after = data.get("retry_after", "unknown")
113
+ raise DiscordNotificationError(
114
+ f"Rate limited by Discord API. retry_after={retry_after}s"
115
+ )
116
+
117
+ if response.status_code not in (200, 201, 204):
118
+ raise DiscordNotificationError(
119
+ f"HTTP {response.status_code} from Discord API: {response.text}"
120
+ )
121
+
122
+ except requests.exceptions.RequestException as e:
123
+ raise DiscordNotificationError(
124
+ f"Network error while sending Discord notification: {e}"
125
+ ) from e
126
+
127
+ def close(self) -> None:
128
+ """Releases the underlying HTTP session."""
129
+ self.session.close()
130
+
131
+ def __enter__(self) -> DiscordNotifier:
132
+ return self
133
+
134
+ def __exit__(self, *_: object) -> None:
135
+ self.close()
@@ -0,0 +1 @@
1
+ from core_lib.file_utils.file_utils import load_file_content as load_file_content
@@ -0,0 +1,29 @@
1
+ """Utility functions for safe file input/output operations."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from pathlib import Path
6
+
7
+ from core_lib.logger import logger
8
+
9
+
10
+ def load_file_content(filepath: Path | str) -> str:
11
+ """Safely reads a text file if it exists and is accessible.
12
+
13
+ Returns the content as a string, or an empty string if the file
14
+ does not exist, is not a file, or fails to read.
15
+ """
16
+ path = Path(filepath)
17
+
18
+ if not path.exists():
19
+ return ""
20
+
21
+ if not path.is_file():
22
+ logger.warning(f"[file utils] Path is not a valid file: '{path}'.")
23
+ return ""
24
+
25
+ try:
26
+ return path.read_text(encoding="utf-8")
27
+ except Exception as e:
28
+ logger.error(f"[file utils] Failed to read file '{path}'", exception=e)
29
+ return ""
@@ -0,0 +1,16 @@
1
+ """Google Drive client submodule — authentication, service, and helpers."""
2
+
3
+ from __future__ import annotations
4
+
5
+
6
+ def __getattr__(name: str) -> object:
7
+ if name == "GDriveService":
8
+ from core_lib.gdrive.gdrive_service import GDriveService
9
+ return GDriveService
10
+ if name == "get_google_service_credentials":
11
+ from core_lib.gdrive.gdrive_auth import get_google_service_credentials
12
+ return get_google_service_credentials
13
+ if name == "sanitize_gdrive_folder_id":
14
+ from core_lib.gdrive.gdrive_helpers import sanitize_gdrive_folder_id
15
+ return sanitize_gdrive_folder_id
16
+ raise AttributeError(f"module 'core_lib.gdrive' has no attribute {name!r}")