devkitx 1.0.0__tar.gz → 1.0.1__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 (95) hide show
  1. devkitx-1.0.1/PKG-INFO +535 -0
  2. devkitx-1.0.1/README.md +478 -0
  3. {devkitx-1.0.0 → devkitx-1.0.1}/examples/README.md +3 -3
  4. devkitx-1.0.1/pyproject.toml +155 -0
  5. devkitx-1.0.1/src/devkitx/__init__.py +67 -0
  6. devkitx-1.0.1/src/devkitx/_version.py +3 -0
  7. devkitx-1.0.1/src/devkitx/async_utils/__init__.py +14 -0
  8. devkitx-1.0.1/src/devkitx/async_utils/bridges.py +82 -0
  9. devkitx-1.0.1/src/devkitx/async_utils/concurrency.py +56 -0
  10. devkitx-1.0.1/src/devkitx/http_utils/__init__.py +32 -0
  11. devkitx-1.0.1/src/devkitx/http_utils/client.py +133 -0
  12. devkitx-1.0.1/src/devkitx/http_utils/retry.py +90 -0
  13. devkitx-1.0.1/src/devkitx/json_utils/__init__.py +40 -0
  14. devkitx-1.0.1/src/devkitx/json_utils/flatten.py +129 -0
  15. devkitx-1.0.1/src/devkitx/security_utils/__init__.py +13 -0
  16. devkitx-1.0.1/src/devkitx/security_utils/jwt_.py +151 -0
  17. devkitx-1.0.0/PKG-INFO +0 -560
  18. devkitx-1.0.0/README.md +0 -513
  19. devkitx-1.0.0/pyproject.toml +0 -95
  20. devkitx-1.0.0/src/devtools_py/__init__.py +0 -62
  21. devkitx-1.0.0/src/devtools_py/async_utils.py +0 -436
  22. devkitx-1.0.0/src/devtools_py/http_utils.py +0 -346
  23. devkitx-1.0.0/venv/lib/python3.13/site-packages/PyJWT-2.10.1.dist-info/LICENSE +0 -21
  24. devkitx-1.0.0/venv/lib/python3.13/site-packages/anyio-4.10.0.dist-info/licenses/LICENSE +0 -20
  25. devkitx-1.0.0/venv/lib/python3.13/site-packages/attrs-25.3.0.dist-info/licenses/LICENSE +0 -21
  26. devkitx-1.0.0/venv/lib/python3.13/site-packages/bcrypt-4.3.0.dist-info/LICENSE +0 -201
  27. devkitx-1.0.0/venv/lib/python3.13/site-packages/black-25.1.0.dist-info/licenses/LICENSE +0 -21
  28. devkitx-1.0.0/venv/lib/python3.13/site-packages/blib2to3/LICENSE +0 -254
  29. devkitx-1.0.0/venv/lib/python3.13/site-packages/dev_qol_toolkit-0.1.0.dist-info/licenses/LICENSE +0 -0
  30. devkitx-1.0.0/venv/lib/python3.13/site-packages/devtools_py-1.0.0.dist-info/licenses/LICENSE +0 -0
  31. devkitx-1.0.0/venv/lib/python3.13/site-packages/iniconfig-2.1.0.dist-info/licenses/LICENSE +0 -21
  32. devkitx-1.0.0/venv/lib/python3.13/site-packages/mypy/typeshed/LICENSE +0 -237
  33. devkitx-1.0.0/venv/lib/python3.13/site-packages/mypy-1.18.1.dist-info/licenses/LICENSE +0 -229
  34. devkitx-1.0.0/venv/lib/python3.13/site-packages/mypy_extensions-1.1.0.dist-info/licenses/LICENSE +0 -27
  35. devkitx-1.0.0/venv/lib/python3.13/site-packages/pathspec-0.12.1.dist-info/LICENSE +0 -373
  36. devkitx-1.0.0/venv/lib/python3.13/site-packages/pip-25.2.dist-info/licenses/src/pip/_vendor/certifi/LICENSE +0 -20
  37. devkitx-1.0.0/venv/lib/python3.13/site-packages/pip-25.2.dist-info/licenses/src/pip/_vendor/distro/LICENSE +0 -202
  38. devkitx-1.0.0/venv/lib/python3.13/site-packages/pip-25.2.dist-info/licenses/src/pip/_vendor/packaging/LICENSE +0 -3
  39. devkitx-1.0.0/venv/lib/python3.13/site-packages/pip-25.2.dist-info/licenses/src/pip/_vendor/pkg_resources/LICENSE +0 -17
  40. devkitx-1.0.0/venv/lib/python3.13/site-packages/pip-25.2.dist-info/licenses/src/pip/_vendor/platformdirs/LICENSE +0 -21
  41. devkitx-1.0.0/venv/lib/python3.13/site-packages/pip-25.2.dist-info/licenses/src/pip/_vendor/resolvelib/LICENSE +0 -13
  42. devkitx-1.0.0/venv/lib/python3.13/site-packages/pip-25.2.dist-info/licenses/src/pip/_vendor/tomli/LICENSE +0 -21
  43. devkitx-1.0.0/venv/lib/python3.13/site-packages/pip-25.2.dist-info/licenses/src/pip/_vendor/tomli_w/LICENSE +0 -21
  44. devkitx-1.0.0/venv/lib/python3.13/site-packages/pip-25.2.dist-info/licenses/src/pip/_vendor/truststore/LICENSE +0 -21
  45. devkitx-1.0.0/venv/lib/python3.13/site-packages/platformdirs-4.4.0.dist-info/licenses/LICENSE +0 -21
  46. devkitx-1.0.0/venv/lib/python3.13/site-packages/pluggy-1.6.0.dist-info/licenses/LICENSE +0 -21
  47. devkitx-1.0.0/venv/lib/python3.13/site-packages/pygments-2.19.2.dist-info/licenses/LICENSE +0 -25
  48. devkitx-1.0.0/venv/lib/python3.13/site-packages/pyproject_hooks-1.2.0.dist-info/LICENSE +0 -21
  49. devkitx-1.0.0/venv/lib/python3.13/site-packages/pytest-8.4.2.dist-info/licenses/LICENSE +0 -21
  50. devkitx-1.0.0/venv/lib/python3.13/site-packages/pytest_asyncio-1.2.0.dist-info/licenses/LICENSE +0 -201
  51. devkitx-1.0.0/venv/lib/python3.13/site-packages/pytest_cov-7.0.0.dist-info/licenses/LICENSE +0 -21
  52. devkitx-1.0.0/venv/lib/python3.13/site-packages/requests-2.32.5.dist-info/licenses/LICENSE +0 -175
  53. devkitx-1.0.0/venv/lib/python3.13/site-packages/rich-14.1.0.dist-info/LICENSE +0 -19
  54. devkitx-1.0.0/venv/lib/python3.13/site-packages/ruff-0.13.0.dist-info/licenses/LICENSE +0 -430
  55. devkitx-1.0.0/venv/lib/python3.13/site-packages/sniffio-1.3.1.dist-info/LICENSE +0 -3
  56. devkitx-1.0.0/venv/lib/python3.13/site-packages/sortedcontainers-2.4.0.dist-info/LICENSE +0 -13
  57. devkitx-1.0.0/venv/lib/python3.13/site-packages/types_requests-2.32.4.20250809.dist-info/licenses/LICENSE +0 -237
  58. devkitx-1.0.0/venv/lib/python3.13/site-packages/typing_extensions-4.15.0.dist-info/licenses/LICENSE +0 -279
  59. {devkitx-1.0.0 → devkitx-1.0.1}/.gitignore +0 -0
  60. {devkitx-1.0.0 → devkitx-1.0.1}/LICENSE +0 -0
  61. {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/__main__.py +0 -0
  62. {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/cli_utils.py +0 -0
  63. {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/config_utils.py +0 -0
  64. {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/data_utils.py +0 -0
  65. {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/dev_utils.py +0 -0
  66. {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/file_utils.py +0 -0
  67. {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/json_utils.py +0 -0
  68. {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/log_utils.py +0 -0
  69. {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/py.typed +0 -0
  70. {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/security_utils.py +0 -0
  71. {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/string_utils.py +0 -0
  72. {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/system_utils.py +0 -0
  73. {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/time_utils.py +0 -0
  74. {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/validation_utils.py +0 -0
  75. {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/build-1.3.0.dist-info/licenses/LICENSE +0 -0
  76. {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/certifi-2025.8.3.dist-info/licenses/LICENSE +0 -0
  77. {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/charset_normalizer-3.4.3.dist-info/licenses/LICENSE +0 -0
  78. {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/id-1.5.0.dist-info/LICENSE +0 -0
  79. {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/jaraco.classes-3.4.0.dist-info/LICENSE +0 -0
  80. {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/jaraco.context-6.0.1.dist-info/LICENSE +0 -0
  81. {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/jaraco_functools-4.3.0.dist-info/licenses/LICENSE +0 -0
  82. {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/keyring-25.6.0.dist-info/LICENSE +0 -0
  83. {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/markdown_it_py-4.0.0.dist-info/licenses/LICENSE +0 -0
  84. {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/mdurl-0.1.2.dist-info/LICENSE +0 -0
  85. {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/more_itertools-10.8.0.dist-info/licenses/LICENSE +0 -0
  86. {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/nh3-0.3.0.dist-info/licenses/LICENSE +0 -0
  87. {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/packaging-25.0.dist-info/licenses/LICENSE +0 -0
  88. {devkitx-1.0.0/venv/lib/python3.13/site-packages/pip-25.2.dist-info/licenses/src/pip/_vendor/pygments → devkitx-1.0.1/venv/lib/python3.13/site-packages/pygments-2.19.2.dist-info/licenses}/LICENSE +0 -0
  89. {devkitx-1.0.0/venv/lib/python3.13/site-packages/pip-25.2.dist-info/licenses/src/pip/_vendor/pyproject_hooks → devkitx-1.0.1/venv/lib/python3.13/site-packages/pyproject_hooks-1.2.0.dist-info}/LICENSE +0 -0
  90. {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/readme_renderer-44.0.dist-info/LICENSE +0 -0
  91. {devkitx-1.0.0/venv/lib/python3.13/site-packages/pip-25.2.dist-info/licenses/src/pip/_vendor/requests → devkitx-1.0.1/venv/lib/python3.13/site-packages/requests-2.32.5.dist-info/licenses}/LICENSE +0 -0
  92. {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/requests_toolbelt-1.0.0.dist-info/LICENSE +0 -0
  93. {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/rfc3986-2.0.0.dist-info/LICENSE +0 -0
  94. {devkitx-1.0.0/venv/lib/python3.13/site-packages/pip-25.2.dist-info/licenses/src/pip/_vendor/rich → devkitx-1.0.1/venv/lib/python3.13/site-packages/rich-14.1.0.dist-info}/LICENSE +0 -0
  95. {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/twine-6.2.0.dist-info/licenses/LICENSE +0 -0
devkitx-1.0.1/PKG-INFO ADDED
@@ -0,0 +1,535 @@
1
+ Metadata-Version: 2.4
2
+ Name: devkitx
3
+ Version: 1.0.1
4
+ Summary: A pragmatic Python toolkit: HTTP, JSON, async bridges, security, CLI.
5
+ Project-URL: Homepage, https://github.com/ladycami/devkitx
6
+ Project-URL: Issues, https://github.com/ladycami/devkitx/issues
7
+ Project-URL: Docs, https://github.com/ladycami/devkitx#readme
8
+ Author: LadyCami
9
+ License: MIT
10
+ License-File: LICENSE
11
+ Keywords: async,bcrypt,cli,colored-output,configuration,cross-platform,debugging,developer-tools,devtools,env-files,files,http,json,jwt,logging,profiling,progress-bars,retry-logic,security,string-manipulation,system-utils,time-utils,toml,type-safe,utilities,validation,yaml
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: License :: OSI Approved :: MIT License
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3 :: Only
19
+ Classifier: Programming Language :: Python :: 3.10
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
24
+ Classifier: Topic :: Security :: Cryptography
25
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
26
+ Classifier: Topic :: System :: Systems Administration
27
+ Classifier: Topic :: Text Processing :: General
28
+ Classifier: Topic :: Utilities
29
+ Classifier: Typing :: Typed
30
+ Requires-Python: >=3.10
31
+ Requires-Dist: typing-extensions>=4.6; python_version < '3.11'
32
+ Provides-Extra: bcrypt
33
+ Requires-Dist: bcrypt>=4.1; extra == 'bcrypt'
34
+ Provides-Extra: cli
35
+ Requires-Dist: click>=8.1; extra == 'cli'
36
+ Requires-Dist: rich>=13.7; extra == 'cli'
37
+ Provides-Extra: dev
38
+ Requires-Dist: black>=24.0; extra == 'dev'
39
+ Requires-Dist: build>=1.2; extra == 'dev'
40
+ Requires-Dist: hypothesis>=6.0; extra == 'dev'
41
+ Requires-Dist: mypy>=1.10; extra == 'dev'
42
+ Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
43
+ Requires-Dist: pytest-cov>=5.0; extra == 'dev'
44
+ Requires-Dist: pytest>=8.0; extra == 'dev'
45
+ Requires-Dist: ruff>=0.5; extra == 'dev'
46
+ Requires-Dist: twine>=5.1; extra == 'dev'
47
+ Provides-Extra: http
48
+ Requires-Dist: httpx<0.28,>=0.27; extra == 'http'
49
+ Provides-Extra: jwt
50
+ Requires-Dist: pyjwt[crypto]>=2.8; extra == 'jwt'
51
+ Provides-Extra: toml
52
+ Requires-Dist: tomli-w>=1.0.0; extra == 'toml'
53
+ Requires-Dist: tomli>=2.0.1; (python_version < '3.11') and extra == 'toml'
54
+ Provides-Extra: yaml
55
+ Requires-Dist: pyyaml>=6.0.1; extra == 'yaml'
56
+ Description-Content-Type: text/markdown
57
+
58
+ # DevKitX
59
+
60
+ **A pragmatic Python toolkit: HTTP, JSON, async bridges, security, CLI**
61
+
62
+ DevKitX is a modern, type-safe toolkit providing essential utilities for common development tasks. This package was previously named `devtools-py` but has been renamed to `devkitx` to avoid confusion with Samuel Colvin's `devtools` package (which focuses on pretty-printing and debugging).
63
+
64
+ > **Note**: This is **not** the same as Samuel Colvin's `devtools` package. DevKitX provides a broader set of utilities including HTTP clients, async bridges, security functions, and more.
65
+
66
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
67
+ [![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
68
+ [![Typed](https://img.shields.io/badge/typed-yes-brightgreen.svg)](https://mypy-lang.org/)
69
+ [![Development Status](https://img.shields.io/badge/status-beta-orange.svg)](https://pypi.org/project/devkitx/)
70
+
71
+ ## Features
72
+
73
+ - 🚀 **Modern Python**: Built for Python 3.10+ with full type annotations
74
+ - ⚡ **Async Support**: Bridges between sync/async code with safe event loop handling
75
+ - 🌐 **HTTP Client**: HTTP utilities with safe defaults, timeouts, and retry logic
76
+ - 📦 **JSON Utils**: Flatten nested JSON structures with configurable separators
77
+ - 🔒 **Security**: JWT tokens with safe defaults and proper claim validation
78
+ - 🎯 **Minimal Core**: Lightweight base package with optional extras for specific features
79
+
80
+ ## Installation
81
+
82
+ ### Basic Installation
83
+
84
+ ```bash
85
+ pip install devkitx
86
+ ```
87
+
88
+ ### Installation with Optional Features
89
+
90
+ DevKitX uses optional dependencies to keep the core package lightweight. Install only the features you need:
91
+
92
+ | Extra | Dependencies | Features |
93
+ |-------|-------------|----------|
94
+ | `http` | `httpx` | HTTP clients with safe defaults and retry logic |
95
+ | `cli` | `click`, `rich` | Command-line interfaces and rich terminal output |
96
+ | `jwt` | `PyJWT[crypto]` | JWT token generation and verification |
97
+ | `bcrypt` | `bcrypt` | Password hashing utilities |
98
+ | `yaml` | `pyyaml` | YAML configuration support |
99
+ | `toml` | `tomli`, `tomli-w` | TOML configuration support |
100
+
101
+ ```bash
102
+ # Install with HTTP utilities
103
+ pip install "devkitx[http]"
104
+
105
+ # Install with multiple extras
106
+ pip install "devkitx[http,jwt,cli]"
107
+
108
+ # Install all extras
109
+ pip install "devkitx[http,cli,jwt,bcrypt,yaml,toml]"
110
+
111
+ # Development installation
112
+ pip install "devkitx[dev]"
113
+ ```
114
+
115
+ ## Quick Start
116
+
117
+ ```python
118
+ # Core utilities (always available)
119
+ from devkitx import flatten_json, async_to_sync, sync_to_async
120
+
121
+ # Flatten nested JSON structures
122
+ data = {"user": {"profile": {"name": "John", "age": 30}}}
123
+ flat_data = flatten_json(data)
124
+ # Result: {"user.profile.name": "John", "user.profile.age": 30}
125
+
126
+ # Bridge between sync and async code
127
+ import asyncio
128
+
129
+ async def async_function(x):
130
+ await asyncio.sleep(0.1)
131
+ return x * 2
132
+
133
+ # Convert async function to sync
134
+ sync_func = async_to_sync(async_function)
135
+ result = sync_func(5) # Works without event loop
136
+
137
+ # Convert sync function to async
138
+ def slow_function(x):
139
+ import time
140
+ time.sleep(0.1)
141
+ return x * 2
142
+
143
+ async_func = sync_to_async(slow_function)
144
+ result = await async_func(5) # Non-blocking
145
+ ```
146
+
147
+ ### HTTP Utilities (requires `http` extra)
148
+
149
+ ```python
150
+ # Install with: pip install "devkitx[http]"
151
+ from devkitx import make_client, make_async_client
152
+
153
+ # HTTP client with safe defaults
154
+ client = make_client(base_url="https://api.example.com")
155
+ response = client.get("/users")
156
+
157
+ # Async HTTP client
158
+ async def fetch_data():
159
+ async_client = make_async_client()
160
+ response = await async_client.get("https://api.example.com/data")
161
+ return response.json()
162
+ ```
163
+
164
+ ### JWT Utilities (requires `jwt` extra)
165
+
166
+ ```python
167
+ # Install with: pip install "devkitx[jwt]"
168
+ from devkitx.security_utils.jwt_ import generate_jwt_token, verify_jwt_token
169
+
170
+ # Generate JWT with safe defaults
171
+ payload = {"user_id": 123, "role": "admin"}
172
+ token = generate_jwt_token(
173
+ payload,
174
+ secret="your-secret-key",
175
+ expires_in=3600, # 1 hour
176
+ issuer="your-app",
177
+ audience="your-users"
178
+ )
179
+
180
+ # Verify JWT token
181
+ try:
182
+ decoded = verify_jwt_token(
183
+ token,
184
+ secret="your-secret-key",
185
+ issuer="your-app",
186
+ audience="your-users"
187
+ )
188
+ print(f"User ID: {decoded['user_id']}")
189
+ except Exception as e:
190
+ print(f"Invalid token: {e}")
191
+ ```
192
+
193
+ ## Core Utilities
194
+
195
+ ### JSON Utilities
196
+
197
+ Flatten nested JSON structures for easier processing:
198
+
199
+ ```python
200
+ from devkitx import flatten_json
201
+
202
+ # Flatten nested JSON structures
203
+ nested = {"user": {"profile": {"name": "John", "age": 30}}}
204
+ flat = flatten_json(nested)
205
+ # Result: {"user.profile.name": "John", "user.profile.age": 30}
206
+
207
+ # Custom separator
208
+ flat_custom = flatten_json(nested, sep="_")
209
+ # Result: {"user_profile_name": "John", "user_profile_age": 30}
210
+
211
+ # Works with arrays too
212
+ data = {"items": [{"id": 1, "name": "first"}, {"id": 2, "name": "second"}]}
213
+ flat = flatten_json(data)
214
+ # Result: {"items.0.id": 1, "items.0.name": "first", "items.1.id": 2, "items.1.name": "second"}
215
+ ```
216
+
217
+ ### Async Bridge Utilities
218
+
219
+ Convert between sync and async functions safely:
220
+
221
+ ```python
222
+ from devkitx import async_to_sync, sync_to_async
223
+ import asyncio
224
+
225
+ # Convert async function to sync
226
+ async def fetch_data(url):
227
+ # Simulate async HTTP request
228
+ await asyncio.sleep(0.1)
229
+ return f"Data from {url}"
230
+
231
+ sync_fetch = async_to_sync(fetch_data)
232
+ result = sync_fetch("https://api.example.com") # Works without event loop
233
+
234
+ # Convert sync function to async
235
+ def process_data(data):
236
+ # Simulate CPU-intensive work
237
+ import time
238
+ time.sleep(0.1)
239
+ return data.upper()
240
+
241
+ async_process = sync_to_async(process_data)
242
+ result = await async_process("hello") # Non-blocking
243
+
244
+ # Concurrency control (requires async_utils module)
245
+ from devkitx.async_utils.concurrency import gather_with_limit
246
+
247
+ async def fetch_multiple():
248
+ urls = ["https://api.example.com/1", "https://api.example.com/2"]
249
+ tasks = [fetch_data(url) for url in urls]
250
+ # Limit to 5 concurrent operations
251
+ results = await gather_with_limit(5, *tasks)
252
+ return results
253
+ ```
254
+
255
+ ## Optional Utilities
256
+
257
+ ### HTTP Utilities (requires `http` extra)
258
+
259
+ HTTP clients with safe defaults and retry logic:
260
+
261
+ ```python
262
+ # Install with: pip install "devkitx[http]"
263
+ from devkitx import make_client, make_async_client
264
+ from devkitx.http_utils.retry import with_retries
265
+
266
+ # Create HTTP client with safe defaults
267
+ # - 10s connect timeout, 15s read timeout
268
+ # - Connection pooling with limits
269
+ # - HTTP/2 support
270
+ client = make_client(
271
+ base_url="https://api.example.com",
272
+ headers={"Authorization": "Bearer token"}
273
+ )
274
+
275
+ response = client.get("/users")
276
+ print(response.json())
277
+
278
+ # Async HTTP client
279
+ async def fetch_data():
280
+ async_client = make_async_client(base_url="https://api.example.com")
281
+ response = await async_client.get("/data")
282
+ return response.json()
283
+
284
+ # Retry logic with exponential backoff
285
+ def unreliable_request():
286
+ response = client.get("/flaky-endpoint")
287
+ if response.status_code >= 500:
288
+ raise Exception("Server error")
289
+ return response
290
+
291
+ # Retry up to 3 times with exponential backoff and jitter
292
+ result = with_retries(
293
+ unreliable_request,
294
+ retries=3,
295
+ base_delay=0.2,
296
+ jitter=0.2
297
+ )
298
+ ```
299
+
300
+ ### Security Utilities (requires `jwt` extra)
301
+
302
+ JWT token utilities with safe defaults:
303
+
304
+ ```python
305
+ # Install with: pip install "devkitx[jwt]"
306
+ from devkitx.security_utils.jwt_ import generate_jwt_token, verify_jwt_token
307
+
308
+ # Generate JWT token with safe defaults
309
+ # - Uses HS256 algorithm
310
+ # - Requires exp and iat claims
311
+ # - Supports issuer and audience validation
312
+ payload = {"user_id": 123, "role": "admin"}
313
+ token = generate_jwt_token(
314
+ payload,
315
+ secret="your-secret-key",
316
+ expires_in=3600, # 1 hour
317
+ issuer="your-app",
318
+ audience="your-users"
319
+ )
320
+
321
+ # Verify JWT token with proper validation
322
+ try:
323
+ decoded = verify_jwt_token(
324
+ token,
325
+ secret="your-secret-key",
326
+ issuer="your-app",
327
+ audience="your-users",
328
+ leeway=10 # Allow 10 seconds clock skew
329
+ )
330
+ print(f"User: {decoded['user_id']}, Role: {decoded['role']}")
331
+ except Exception as e:
332
+ print(f"Token validation failed: {e}")
333
+ ```
334
+
335
+ > **Security Note**: JWT utilities use HS256 algorithm by default and require proper secret key management. Always validate issuer, audience, and implement key rotation in production.
336
+
337
+ ## API Reference
338
+
339
+ For detailed API documentation, see the individual module files:
340
+
341
+ - **Core utilities**: Always available after `pip install devkitx`
342
+ - `flatten_json()` - Flatten nested JSON structures
343
+ - `async_to_sync()` - Convert async functions to sync
344
+ - `sync_to_async()` - Convert sync functions to async
345
+
346
+ - **HTTP utilities**: Available with `pip install "devkitx[http]"`
347
+ - `make_client()` - Create HTTP client with safe defaults
348
+ - `make_async_client()` - Create async HTTP client
349
+ - `with_retries()` - Retry logic with exponential backoff
350
+
351
+ - **Security utilities**: Available with `pip install "devkitx[jwt]"`
352
+ - `generate_jwt_token()` - Generate JWT tokens with safe defaults
353
+ - `verify_jwt_token()` - Verify JWT tokens with proper validation
354
+
355
+ - **Async utilities**: Advanced async patterns
356
+ - `gather_with_limit()` - Execute awaitables with concurrency limits
357
+
358
+ ## Requirements
359
+
360
+ - Python 3.10 or higher
361
+ - Core package has minimal dependencies (only `typing-extensions` for Python < 3.11)
362
+ - Optional features require additional packages (see Installation section)
363
+
364
+ ## Development
365
+
366
+ ```bash
367
+ # Clone the repository
368
+ git clone https://github.com/ladycami/devkitx.git
369
+ cd devkitx
370
+
371
+ # Install in development mode with all extras
372
+ pip install -e ".[http,cli,jwt,bcrypt,yaml,toml,dev]"
373
+
374
+ # Run tests
375
+ pytest
376
+
377
+ # Run linting and type checking
378
+ ruff check .
379
+ mypy devkitx
380
+ ```
381
+
382
+ ## Contributing
383
+
384
+ Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
385
+
386
+ ## License
387
+
388
+ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
389
+
390
+ ## Security Considerations
391
+
392
+ DevKitX includes security utilities with safe defaults, but proper security requires understanding their scope and limitations.
393
+
394
+ ### JWT Security
395
+
396
+ The JWT utilities in DevKitX provide secure defaults but require proper implementation:
397
+
398
+ **Safe Defaults:**
399
+ - Uses HS256 algorithm (HMAC with SHA-256)
400
+ - Requires `exp` (expiration) and `iat` (issued at) claims
401
+ - Supports `iss` (issuer) and `aud` (audience) validation
402
+ - Configurable clock skew tolerance (`leeway`)
403
+
404
+ **Best Practices:**
405
+ ```python
406
+ from devkitx.security_utils.jwt_ import generate_jwt_token, verify_jwt_token
407
+
408
+ # ✅ Good: Include issuer and audience
409
+ token = generate_jwt_token(
410
+ {"user_id": 123},
411
+ secret="your-256-bit-secret",
412
+ expires_in=900, # 15 minutes, not hours
413
+ issuer="your-app-name",
414
+ audience="your-app-users"
415
+ )
416
+
417
+ # ✅ Good: Validate issuer and audience
418
+ decoded = verify_jwt_token(
419
+ token,
420
+ secret="your-256-bit-secret",
421
+ issuer="your-app-name",
422
+ audience="your-app-users"
423
+ )
424
+ ```
425
+
426
+ **Security Requirements:**
427
+ - **Secret Management**: Use strong, randomly generated secrets (≥256 bits)
428
+ - **Key Rotation**: Implement regular secret key rotation
429
+ - **Short Expiration**: Use short-lived tokens (15-60 minutes)
430
+ - **HTTPS Only**: Always transmit tokens over HTTPS
431
+ - **Secure Storage**: Store tokens securely (httpOnly cookies, not localStorage)
432
+
433
+ ### HTTP Security
434
+
435
+ HTTP utilities include safe defaults but don't handle all security concerns:
436
+
437
+ **Included Protections:**
438
+ - Connection timeouts prevent hanging requests
439
+ - Connection pooling limits prevent resource exhaustion
440
+ - HTTP/2 support for better performance
441
+
442
+ **Not Included (implement separately):**
443
+ - Request/response validation
444
+ - Authentication headers management
445
+ - Rate limiting
446
+ - SSL certificate verification (relies on httpx defaults)
447
+
448
+ ### Input Sanitization Scope
449
+
450
+ DevKitX does **not** currently include comprehensive input sanitization. The security utilities focus on:
451
+
452
+ **Covered:**
453
+ - JWT token generation and validation
454
+ - Safe HTTP client defaults
455
+
456
+ **Not Covered (use dedicated libraries):**
457
+ - SQL injection prevention → Use parameterized queries
458
+ - XSS prevention → Use template engines with auto-escaping
459
+ - Command injection prevention → Avoid shell=True, validate inputs
460
+ - Path traversal prevention → Use pathlib, validate file paths
461
+
462
+ ### Recommended Security Libraries
463
+
464
+ For comprehensive security, combine DevKitX with specialized libraries:
465
+
466
+ ```python
467
+ # SQL injection prevention
468
+ import sqlalchemy # Use parameterized queries
469
+
470
+ # XSS prevention
471
+ import markupsafe # Safe HTML handling
472
+ import bleach # HTML sanitization
473
+
474
+ # Input validation
475
+ import pydantic # Data validation with types
476
+ import cerberus # Schema validation
477
+
478
+ # Cryptography
479
+ import cryptography # Advanced crypto operations
480
+ import bcrypt # Password hashing (available as devkitx[bcrypt])
481
+ ```
482
+
483
+ ### Security Reporting
484
+
485
+ If you discover security vulnerabilities in DevKitX, please report them responsibly:
486
+
487
+ 1. **Do not** create public GitHub issues for security vulnerabilities
488
+ 2. Email security concerns to the maintainers
489
+ 3. Include detailed reproduction steps
490
+ 4. Allow reasonable time for fixes before public disclosure
491
+
492
+ ## Package History
493
+
494
+ ### Package Rename Notice
495
+
496
+ This package was previously named `devtools-py` but has been renamed to `devkitx` to avoid confusion with Samuel Colvin's `devtools` package. If you were using the old package name, please update your dependencies:
497
+
498
+ ```bash
499
+ # Old (deprecated)
500
+ pip uninstall devtools-py
501
+ # New
502
+ pip install devkitx
503
+ ```
504
+
505
+ Update your imports:
506
+ ```python
507
+ # Old
508
+ from devtools_py import some_function
509
+ # New
510
+ from devkitx import some_function
511
+ ```
512
+
513
+ ## Changelog
514
+
515
+ ### v1.0.1 (2025-09-16)
516
+
517
+ #### Changed
518
+ - **BREAKING**: Renamed package from `devtools-py` to `devkitx`
519
+ - Updated development status to Beta (was incorrectly marked as Production/Stable)
520
+ - Restructured as lightweight core package with optional extras
521
+ - Updated all project URLs to point to correct repository
522
+
523
+ #### Added
524
+ - HTTP clients with safe defaults (10s connect, 15s read timeout)
525
+ - Async bridge utilities with proper event loop handling
526
+ - JWT utilities with secure defaults and proper validation
527
+ - JSON flattening utility with configurable separators
528
+ - Retry logic with exponential backoff and jitter
529
+ - Type annotations with `py.typed` marker
530
+ - Minimal test suite with CI/CD pipeline
531
+
532
+ #### Fixed
533
+ - Import statements now use correct `devkitx` namespace
534
+ - Package metadata points to correct repository
535
+ - Optional dependencies properly isolated with extras