devkitx 1.0.0__py3-none-any.whl

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.
@@ -0,0 +1,211 @@
1
+ """File system utilities for DevKitX.
2
+
3
+ This module provides utilities for file operations, directory management,
4
+ and file system queries with enhanced error handling.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import os
10
+ import shutil
11
+ import tempfile
12
+ from pathlib import Path
13
+
14
+
15
+ def find_file(name_or_pattern: str, root: str | Path = ".") -> list[Path]:
16
+ """Find files by exact name or glob pattern recursively.
17
+
18
+ Args:
19
+ name_or_pattern: Exact filename or glob pattern to search for
20
+ root: Root directory to search from
21
+
22
+ Returns:
23
+ List of matching file paths, sorted alphabetically
24
+
25
+ Examples:
26
+ >>> find_file("settings.py", ".")
27
+ [PosixPath('./config/settings.py')]
28
+ >>> find_file("*.json", "src")
29
+ [PosixPath('src/config.json'), PosixPath('src/data.json')]
30
+ >>> find_file("README.md") # Case-insensitive fallback
31
+ [PosixPath('./readme.md')]
32
+ """
33
+ root_path = Path(root)
34
+ if any(ch in name_or_pattern for ch in "*?[]"):
35
+ return sorted(root_path.rglob(name_or_pattern))
36
+ # exact name match, case-sensitive then case-insensitive fallback
37
+ exact = [p for p in root_path.rglob("*") if p.is_file() and p.name == name_or_pattern]
38
+ if exact:
39
+ return sorted(exact)
40
+ lowered = name_or_pattern.lower()
41
+ return sorted(p for p in root_path.rglob("*") if p.is_file() and p.name.lower() == lowered)
42
+
43
+
44
+ def ensure_dir(path: str | Path) -> Path:
45
+ """Ensure directory exists, creating it if necessary.
46
+
47
+ Args:
48
+ path: Directory path to create
49
+
50
+ Returns:
51
+ Path object for the created directory
52
+
53
+ Raises:
54
+ PermissionError: If lacking permissions to create directory
55
+ OSError: If unable to create directory for other reasons
56
+
57
+ Examples:
58
+ >>> ensure_dir("output/data")
59
+ PosixPath('output/data')
60
+ >>> ensure_dir(Path("logs"))
61
+ PosixPath('logs')
62
+ """
63
+ p = Path(path)
64
+ p.mkdir(parents=True, exist_ok=True)
65
+ return p
66
+
67
+
68
+ def is_readable(path: str | Path) -> bool:
69
+ """Check if file or directory is readable.
70
+
71
+ Args:
72
+ path: Path to check for read access
73
+
74
+ Returns:
75
+ True if path exists and is readable, False otherwise
76
+
77
+ Examples:
78
+ >>> is_readable("config.json")
79
+ True
80
+ >>> is_readable("/root/secret.txt") # May be False due to permissions
81
+ False
82
+ >>> is_readable("nonexistent.txt")
83
+ False
84
+ """
85
+ p = Path(path)
86
+ try:
87
+ return p.exists() and os.access(p, os.R_OK)
88
+ except Exception:
89
+ return False
90
+
91
+
92
+ def is_writable(path: str | Path) -> bool:
93
+ """Check if file or directory is writable.
94
+
95
+ For existing files, checks write permissions on the file.
96
+ For non-existing files, checks write permissions on the parent directory.
97
+
98
+ Args:
99
+ path: Path to check for write access
100
+
101
+ Returns:
102
+ True if path is writable, False otherwise
103
+
104
+ Examples:
105
+ >>> is_writable("output.txt")
106
+ True
107
+ >>> is_writable("/etc/hosts") # May be False due to permissions
108
+ False
109
+ >>> is_writable("new_file.txt") # Checks parent directory permissions
110
+ True
111
+ """
112
+ p = Path(path)
113
+ try:
114
+ if p.exists():
115
+ return os.access(p, os.W_OK)
116
+ # check parent
117
+ return os.access(p.parent, os.W_OK)
118
+ except Exception:
119
+ return False
120
+
121
+
122
+ def atomic_write(path: str | Path, data: bytes | str) -> Path:
123
+ """Write data to file atomically using temporary file.
124
+
125
+ Writes to a temporary file first, then atomically moves it to the target
126
+ location. This prevents partial writes and corruption if the process is
127
+ interrupted.
128
+
129
+ Args:
130
+ path: Target file path
131
+ data: Data to write (string or bytes)
132
+
133
+ Returns:
134
+ Path object for the written file
135
+
136
+ Raises:
137
+ PermissionError: If lacking write permissions
138
+ OSError: If unable to create temporary file or move it
139
+
140
+ Examples:
141
+ >>> atomic_write("config.json", '{"key": "value"}')
142
+ PosixPath('config.json')
143
+ >>> atomic_write("data.bin", b"binary data")
144
+ PosixPath('data.bin')
145
+ """
146
+ target = Path(path)
147
+ target.parent.mkdir(parents=True, exist_ok=True)
148
+ mode = "wb" if isinstance(data, (bytes, bytearray)) else "w"
149
+ with tempfile.NamedTemporaryFile(delete=False, dir=target.parent) as tf:
150
+ tmp_path = Path(tf.name)
151
+ with tmp_path.open(mode, encoding=None if "b" in mode else "utf-8") as f:
152
+ f.write(data) # type: ignore[arg-type]
153
+ os.replace(tmp_path, target)
154
+ return target
155
+
156
+
157
+ def glob_ext(root: str | Path, ext: str) -> list[Path]:
158
+ """Find all files with given extension recursively.
159
+
160
+ Args:
161
+ root: Root directory to search from
162
+ ext: File extension (with or without leading dot)
163
+
164
+ Returns:
165
+ List of matching file paths, sorted alphabetically
166
+
167
+ Examples:
168
+ >>> glob_ext("src", "py")
169
+ [PosixPath('src/main.py'), PosixPath('src/utils.py')]
170
+ >>> glob_ext("data", ".json")
171
+ [PosixPath('data/config.json'), PosixPath('data/users.json')]
172
+ >>> glob_ext(Path("docs"), "md")
173
+ [PosixPath('docs/README.md'), PosixPath('docs/guide.md')]
174
+ """
175
+ e = ext if ext.startswith(".") else f".{ext}"
176
+ return sorted(Path(root).rglob(f"*{e}"))
177
+
178
+
179
+ def copy_file(src: str | Path, dst: str | Path, overwrite: bool = True) -> Path:
180
+ """Copy file from source to destination.
181
+
182
+ Args:
183
+ src: Source file path
184
+ dst: Destination file path
185
+ overwrite: Whether to overwrite existing destination file
186
+
187
+ Returns:
188
+ Path object for the destination file
189
+
190
+ Raises:
191
+ FileNotFoundError: If source file doesn't exist
192
+ FileExistsError: If destination exists and overwrite is False
193
+ PermissionError: If lacking read/write permissions
194
+ OSError: If unable to create parent directories
195
+
196
+ Examples:
197
+ >>> copy_file("source.txt", "backup.txt")
198
+ PosixPath('backup.txt')
199
+ >>> copy_file("data.json", "archive/data.json")
200
+ PosixPath('archive/data.json')
201
+ >>> copy_file("file.txt", "existing.txt", overwrite=False)
202
+ Traceback (most recent call last):
203
+ ...
204
+ FileExistsError: existing.txt
205
+ """
206
+ src_p, dst_p = Path(src), Path(dst)
207
+ dst_p.parent.mkdir(parents=True, exist_ok=True)
208
+ if dst_p.exists() and not overwrite:
209
+ raise FileExistsError(dst_p)
210
+ shutil.copy2(src_p, dst_p)
211
+ return dst_p
@@ -0,0 +1,346 @@
1
+ """HTTP utilities for DevKitX.
2
+
3
+ This module provides utilities for making HTTP requests with retry logic,
4
+ async support, and convenient API client classes.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import asyncio
10
+ import time
11
+ from typing import Any, Iterable, Mapping, MutableMapping
12
+
13
+ import httpx
14
+
15
+
16
+ RETRY_STATUSES = {429, 500, 502, 503, 504}
17
+
18
+
19
+ def _sleep_backoff(attempt: int, base: float = 0.25, cap: float = 4.0) -> None:
20
+ delay = min(cap, base * (2 ** (attempt - 1)))
21
+ time.sleep(delay)
22
+
23
+
24
+ def _merge_headers(
25
+ base: Mapping[str, str] | None, extra: Mapping[str, str] | None
26
+ ) -> MutableMapping[str, str]:
27
+ out: dict[str, str] = {}
28
+ if base:
29
+ out.update(base)
30
+ if extra:
31
+ out.update(extra)
32
+ return out
33
+
34
+
35
+ def api_request(
36
+ method: str,
37
+ url: str,
38
+ *,
39
+ headers: Mapping[str, str] | None = None,
40
+ json_body: Any | None = None,
41
+ params: Mapping[str, Any] | None = None,
42
+ timeout: float = 15.0,
43
+ retries: int = 3,
44
+ ) -> Any:
45
+ """Make synchronous HTTP request with automatic retries.
46
+
47
+ Automatically retries on common transient failures (429, 5xx status codes)
48
+ with exponential backoff. Returns parsed JSON when possible, otherwise text.
49
+
50
+ Args:
51
+ method: HTTP method (GET, POST, PUT, DELETE, etc.)
52
+ url: Target URL
53
+ headers: Optional HTTP headers
54
+ json_body: Optional JSON body for request
55
+ params: Optional query parameters
56
+ timeout: Request timeout in seconds
57
+ retries: Number of retry attempts
58
+
59
+ Returns:
60
+ Parsed JSON response or text content
61
+
62
+ Raises:
63
+ httpx.HTTPStatusError: For HTTP error status codes (after retries)
64
+ httpx.RequestError: For network-related errors (after retries)
65
+
66
+ Examples:
67
+ >>> response = api_request("GET", "https://api.example.com/users")
68
+ >>> user_data = api_request("POST", "https://api.example.com/users",
69
+ ... json_body={"name": "John", "email": "john@example.com"})
70
+ >>> api_request("GET", "https://api.example.com/data",
71
+ ... headers={"Authorization": "Bearer token"},
72
+ ... params={"page": 1, "limit": 10})
73
+ """
74
+ hdrs = _merge_headers({"accept": "application/json"}, headers)
75
+ last_exc: Exception | None = None
76
+
77
+ for attempt in range(1, retries + 1):
78
+ try:
79
+ with httpx.Client(http2=True, timeout=timeout, follow_redirects=True) as client:
80
+ resp = client.request(
81
+ method.upper(), url, headers=hdrs, json=json_body, params=params
82
+ )
83
+ if resp.status_code in RETRY_STATUSES and attempt < retries:
84
+ _sleep_backoff(attempt)
85
+ continue
86
+ resp.raise_for_status()
87
+ ctype = resp.headers.get("content-type", "")
88
+ if "application/json" in ctype:
89
+ return resp.json()
90
+ return resp.text
91
+ except Exception as exc:
92
+ last_exc = exc
93
+ if attempt >= retries:
94
+ raise
95
+ _sleep_backoff(attempt)
96
+ if last_exc:
97
+ raise last_exc
98
+
99
+
100
+ class BaseAPIClient:
101
+ """Synchronous API client for making HTTP requests to a base URL.
102
+
103
+ Examples:
104
+ >>> client = BaseAPIClient("https://api.example.com")
105
+ >>> users = client.get("/users")
106
+ >>> new_user = client.post("/users", json_body={"name": "John"})
107
+
108
+ >>> # With authentication headers
109
+ >>> client = BaseAPIClient("https://api.example.com",
110
+ ... headers={"Authorization": "Bearer token"})
111
+ >>> data = client.get("/protected-endpoint")
112
+ """
113
+
114
+ def __init__(
115
+ self, base_url: str, headers: Mapping[str, str] | None = None, timeout: float = 15.0
116
+ ):
117
+ """Initialize API client.
118
+
119
+ Args:
120
+ base_url: Base URL for all requests
121
+ headers: Default headers to include in all requests
122
+ timeout: Default timeout for requests in seconds
123
+ """
124
+ self.base_url = base_url.rstrip("/")
125
+ self.headers = dict(headers or {})
126
+ self.timeout = timeout
127
+
128
+ def _url(self, path: str) -> str:
129
+ """Construct full URL from path."""
130
+ return f"{self.base_url}/{path.lstrip('/')}"
131
+
132
+ def get(self, path: str, **kwargs: Any) -> Any:
133
+ """Make GET request to the specified path."""
134
+ return api_request(
135
+ "GET", self._url(path), headers=self.headers, timeout=self.timeout, **kwargs
136
+ )
137
+
138
+ def post(self, path: str, **kwargs: Any) -> Any:
139
+ """Make POST request to the specified path."""
140
+ return api_request(
141
+ "POST", self._url(path), headers=self.headers, timeout=self.timeout, **kwargs
142
+ )
143
+
144
+ def put(self, path: str, **kwargs: Any) -> Any:
145
+ """Make PUT request to the specified path."""
146
+ return api_request(
147
+ "PUT", self._url(path), headers=self.headers, timeout=self.timeout, **kwargs
148
+ )
149
+
150
+ def delete(self, path: str, **kwargs: Any) -> Any:
151
+ """Make DELETE request to the specified path."""
152
+ return api_request(
153
+ "DELETE", self._url(path), headers=self.headers, timeout=self.timeout, **kwargs
154
+ )
155
+
156
+ def patch(self, path: str, **kwargs: Any) -> Any:
157
+ """Make PATCH request to the specified path."""
158
+ return api_request(
159
+ "PATCH", self._url(path), headers=self.headers, timeout=self.timeout, **kwargs
160
+ )
161
+
162
+
163
+ # Async helpers
164
+ async def _async_sleep_backoff(attempt: int, base: float = 0.25, cap: float = 4.0) -> None:
165
+ """Async version of sleep backoff."""
166
+ delay = min(cap, base * (2 ** (attempt - 1)))
167
+ await asyncio.sleep(delay)
168
+
169
+
170
+ async def async_api_request(
171
+ method: str,
172
+ url: str,
173
+ *,
174
+ headers: Mapping[str, str] | None = None,
175
+ json_body: Any | None = None,
176
+ params: Mapping[str, Any] | None = None,
177
+ timeout: float = 15.0,
178
+ retries: int = 3,
179
+ ) -> Any:
180
+ """
181
+ Async HTTP request with retries/jitter on common transient failures.
182
+ Returns parsed JSON when possible else text.
183
+
184
+ Args:
185
+ method: HTTP method (GET, POST, PUT, DELETE, etc.)
186
+ url: Target URL
187
+ headers: Optional HTTP headers
188
+ json_body: Optional JSON body for request
189
+ params: Optional query parameters
190
+ timeout: Request timeout in seconds
191
+ retries: Number of retry attempts
192
+
193
+ Returns:
194
+ Parsed JSON response or text content
195
+
196
+ Raises:
197
+ httpx.HTTPStatusError: For HTTP error status codes
198
+ httpx.RequestError: For network-related errors
199
+ """
200
+ hdrs = _merge_headers({"accept": "application/json"}, headers)
201
+ last_exc: Exception | None = None
202
+
203
+ for attempt in range(1, retries + 1):
204
+ try:
205
+ async with httpx.AsyncClient(
206
+ http2=True, timeout=timeout, follow_redirects=True
207
+ ) as client:
208
+ resp = await client.request(
209
+ method.upper(), url, headers=hdrs, json=json_body, params=params
210
+ )
211
+ if resp.status_code in RETRY_STATUSES and attempt < retries:
212
+ await _async_sleep_backoff(attempt)
213
+ continue
214
+ resp.raise_for_status()
215
+ ctype = resp.headers.get("content-type", "")
216
+ if "application/json" in ctype:
217
+ return resp.json()
218
+ return resp.text
219
+ except Exception as exc:
220
+ last_exc = exc
221
+ if attempt >= retries:
222
+ raise
223
+ await _async_sleep_backoff(attempt)
224
+ if last_exc:
225
+ raise last_exc
226
+
227
+
228
+ class AsyncAPIClient:
229
+ """Async version of BaseAPIClient for making HTTP requests."""
230
+
231
+ def __init__(
232
+ self, base_url: str, headers: Mapping[str, str] | None = None, timeout: float = 15.0
233
+ ):
234
+ """Initialize async API client.
235
+
236
+ Args:
237
+ base_url: Base URL for all requests
238
+ headers: Default headers to include in all requests
239
+ timeout: Default timeout for requests in seconds
240
+ """
241
+ self.base_url = base_url.rstrip("/")
242
+ self.headers = dict(headers or {})
243
+ self.timeout = timeout
244
+
245
+ def _url(self, path: str) -> str:
246
+ """Construct full URL from path."""
247
+ return f"{self.base_url}/{path.lstrip('/')}"
248
+
249
+ async def get(self, path: str, **kwargs: Any) -> Any:
250
+ """Make async GET request."""
251
+ return await async_api_request(
252
+ "GET", self._url(path), headers=self.headers, timeout=self.timeout, **kwargs
253
+ )
254
+
255
+ async def post(self, path: str, **kwargs: Any) -> Any:
256
+ """Make async POST request."""
257
+ return await async_api_request(
258
+ "POST", self._url(path), headers=self.headers, timeout=self.timeout, **kwargs
259
+ )
260
+
261
+ async def put(self, path: str, **kwargs: Any) -> Any:
262
+ """Make async PUT request."""
263
+ return await async_api_request(
264
+ "PUT", self._url(path), headers=self.headers, timeout=self.timeout, **kwargs
265
+ )
266
+
267
+ async def delete(self, path: str, **kwargs: Any) -> Any:
268
+ """Make async DELETE request."""
269
+ return await async_api_request(
270
+ "DELETE", self._url(path), headers=self.headers, timeout=self.timeout, **kwargs
271
+ )
272
+
273
+ async def patch(self, path: str, **kwargs: Any) -> Any:
274
+ """Make async PATCH request."""
275
+ return await async_api_request(
276
+ "PATCH", self._url(path), headers=self.headers, timeout=self.timeout, **kwargs
277
+ )
278
+
279
+
280
+ async def async_batch_requests(
281
+ requests: Iterable[tuple[str, str, dict[str, Any]]],
282
+ concurrency_limit: int = 10,
283
+ **default_kwargs: Any,
284
+ ) -> list[Any]:
285
+ """Execute multiple HTTP requests concurrently with a concurrency limit.
286
+
287
+ Args:
288
+ requests: Iterable of (method, url, kwargs) tuples
289
+ concurrency_limit: Maximum number of concurrent requests
290
+ **default_kwargs: Default arguments for all requests
291
+
292
+ Returns:
293
+ List of responses in the same order as input requests
294
+
295
+ Example:
296
+ >>> requests = [
297
+ ... ("GET", "https://api.example.com/users/1", {}),
298
+ ... ("GET", "https://api.example.com/users/2", {}),
299
+ ... ("POST", "https://api.example.com/users", {"json_body": {"name": "John"}}),
300
+ ... ]
301
+ >>> responses = await async_batch_requests(requests, concurrency_limit=5)
302
+ """
303
+ # Import here to avoid circular imports
304
+ from .async_utils import gather_with_limit
305
+
306
+ async def make_request(method: str, url: str, kwargs: dict[str, Any]) -> Any:
307
+ merged_kwargs = {**default_kwargs, **kwargs}
308
+ return await async_api_request(method, url, **merged_kwargs)
309
+
310
+ # Create tasks for all requests
311
+ tasks = [make_request(method, url, kwargs) for method, url, kwargs in requests]
312
+
313
+ # Execute with concurrency limit
314
+ return await gather_with_limit(concurrency_limit, *tasks)
315
+
316
+
317
+ async def async_download_file(
318
+ url: str,
319
+ file_path: str,
320
+ *,
321
+ headers: Mapping[str, str] | None = None,
322
+ timeout: float = 30.0,
323
+ chunk_size: int = 8192,
324
+ ) -> None:
325
+ """Download a file asynchronously.
326
+
327
+ Args:
328
+ url: URL to download from
329
+ file_path: Local path to save the file
330
+ headers: Optional HTTP headers
331
+ timeout: Request timeout in seconds
332
+ chunk_size: Size of chunks to read/write
333
+
334
+ Raises:
335
+ httpx.HTTPStatusError: For HTTP error status codes
336
+ httpx.RequestError: For network-related errors
337
+ OSError: For file system errors
338
+ """
339
+ hdrs = _merge_headers({}, headers)
340
+
341
+ async with httpx.AsyncClient(timeout=timeout, follow_redirects=True) as client:
342
+ response = await client.get(url, headers=hdrs)
343
+ response.raise_for_status()
344
+
345
+ with open(file_path, "wb") as file:
346
+ file.write(response.content)