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.
- devkitx-1.0.1/PKG-INFO +535 -0
- devkitx-1.0.1/README.md +478 -0
- {devkitx-1.0.0 → devkitx-1.0.1}/examples/README.md +3 -3
- devkitx-1.0.1/pyproject.toml +155 -0
- devkitx-1.0.1/src/devkitx/__init__.py +67 -0
- devkitx-1.0.1/src/devkitx/_version.py +3 -0
- devkitx-1.0.1/src/devkitx/async_utils/__init__.py +14 -0
- devkitx-1.0.1/src/devkitx/async_utils/bridges.py +82 -0
- devkitx-1.0.1/src/devkitx/async_utils/concurrency.py +56 -0
- devkitx-1.0.1/src/devkitx/http_utils/__init__.py +32 -0
- devkitx-1.0.1/src/devkitx/http_utils/client.py +133 -0
- devkitx-1.0.1/src/devkitx/http_utils/retry.py +90 -0
- devkitx-1.0.1/src/devkitx/json_utils/__init__.py +40 -0
- devkitx-1.0.1/src/devkitx/json_utils/flatten.py +129 -0
- devkitx-1.0.1/src/devkitx/security_utils/__init__.py +13 -0
- devkitx-1.0.1/src/devkitx/security_utils/jwt_.py +151 -0
- devkitx-1.0.0/PKG-INFO +0 -560
- devkitx-1.0.0/README.md +0 -513
- devkitx-1.0.0/pyproject.toml +0 -95
- devkitx-1.0.0/src/devtools_py/__init__.py +0 -62
- devkitx-1.0.0/src/devtools_py/async_utils.py +0 -436
- devkitx-1.0.0/src/devtools_py/http_utils.py +0 -346
- devkitx-1.0.0/venv/lib/python3.13/site-packages/PyJWT-2.10.1.dist-info/LICENSE +0 -21
- devkitx-1.0.0/venv/lib/python3.13/site-packages/anyio-4.10.0.dist-info/licenses/LICENSE +0 -20
- devkitx-1.0.0/venv/lib/python3.13/site-packages/attrs-25.3.0.dist-info/licenses/LICENSE +0 -21
- devkitx-1.0.0/venv/lib/python3.13/site-packages/bcrypt-4.3.0.dist-info/LICENSE +0 -201
- devkitx-1.0.0/venv/lib/python3.13/site-packages/black-25.1.0.dist-info/licenses/LICENSE +0 -21
- devkitx-1.0.0/venv/lib/python3.13/site-packages/blib2to3/LICENSE +0 -254
- devkitx-1.0.0/venv/lib/python3.13/site-packages/dev_qol_toolkit-0.1.0.dist-info/licenses/LICENSE +0 -0
- devkitx-1.0.0/venv/lib/python3.13/site-packages/devtools_py-1.0.0.dist-info/licenses/LICENSE +0 -0
- devkitx-1.0.0/venv/lib/python3.13/site-packages/iniconfig-2.1.0.dist-info/licenses/LICENSE +0 -21
- devkitx-1.0.0/venv/lib/python3.13/site-packages/mypy/typeshed/LICENSE +0 -237
- devkitx-1.0.0/venv/lib/python3.13/site-packages/mypy-1.18.1.dist-info/licenses/LICENSE +0 -229
- devkitx-1.0.0/venv/lib/python3.13/site-packages/mypy_extensions-1.1.0.dist-info/licenses/LICENSE +0 -27
- devkitx-1.0.0/venv/lib/python3.13/site-packages/pathspec-0.12.1.dist-info/LICENSE +0 -373
- devkitx-1.0.0/venv/lib/python3.13/site-packages/pip-25.2.dist-info/licenses/src/pip/_vendor/certifi/LICENSE +0 -20
- devkitx-1.0.0/venv/lib/python3.13/site-packages/pip-25.2.dist-info/licenses/src/pip/_vendor/distro/LICENSE +0 -202
- devkitx-1.0.0/venv/lib/python3.13/site-packages/pip-25.2.dist-info/licenses/src/pip/_vendor/packaging/LICENSE +0 -3
- devkitx-1.0.0/venv/lib/python3.13/site-packages/pip-25.2.dist-info/licenses/src/pip/_vendor/pkg_resources/LICENSE +0 -17
- devkitx-1.0.0/venv/lib/python3.13/site-packages/pip-25.2.dist-info/licenses/src/pip/_vendor/platformdirs/LICENSE +0 -21
- devkitx-1.0.0/venv/lib/python3.13/site-packages/pip-25.2.dist-info/licenses/src/pip/_vendor/resolvelib/LICENSE +0 -13
- devkitx-1.0.0/venv/lib/python3.13/site-packages/pip-25.2.dist-info/licenses/src/pip/_vendor/tomli/LICENSE +0 -21
- devkitx-1.0.0/venv/lib/python3.13/site-packages/pip-25.2.dist-info/licenses/src/pip/_vendor/tomli_w/LICENSE +0 -21
- devkitx-1.0.0/venv/lib/python3.13/site-packages/pip-25.2.dist-info/licenses/src/pip/_vendor/truststore/LICENSE +0 -21
- devkitx-1.0.0/venv/lib/python3.13/site-packages/platformdirs-4.4.0.dist-info/licenses/LICENSE +0 -21
- devkitx-1.0.0/venv/lib/python3.13/site-packages/pluggy-1.6.0.dist-info/licenses/LICENSE +0 -21
- devkitx-1.0.0/venv/lib/python3.13/site-packages/pygments-2.19.2.dist-info/licenses/LICENSE +0 -25
- devkitx-1.0.0/venv/lib/python3.13/site-packages/pyproject_hooks-1.2.0.dist-info/LICENSE +0 -21
- devkitx-1.0.0/venv/lib/python3.13/site-packages/pytest-8.4.2.dist-info/licenses/LICENSE +0 -21
- devkitx-1.0.0/venv/lib/python3.13/site-packages/pytest_asyncio-1.2.0.dist-info/licenses/LICENSE +0 -201
- devkitx-1.0.0/venv/lib/python3.13/site-packages/pytest_cov-7.0.0.dist-info/licenses/LICENSE +0 -21
- devkitx-1.0.0/venv/lib/python3.13/site-packages/requests-2.32.5.dist-info/licenses/LICENSE +0 -175
- devkitx-1.0.0/venv/lib/python3.13/site-packages/rich-14.1.0.dist-info/LICENSE +0 -19
- devkitx-1.0.0/venv/lib/python3.13/site-packages/ruff-0.13.0.dist-info/licenses/LICENSE +0 -430
- devkitx-1.0.0/venv/lib/python3.13/site-packages/sniffio-1.3.1.dist-info/LICENSE +0 -3
- devkitx-1.0.0/venv/lib/python3.13/site-packages/sortedcontainers-2.4.0.dist-info/LICENSE +0 -13
- devkitx-1.0.0/venv/lib/python3.13/site-packages/types_requests-2.32.4.20250809.dist-info/licenses/LICENSE +0 -237
- devkitx-1.0.0/venv/lib/python3.13/site-packages/typing_extensions-4.15.0.dist-info/licenses/LICENSE +0 -279
- {devkitx-1.0.0 → devkitx-1.0.1}/.gitignore +0 -0
- {devkitx-1.0.0 → devkitx-1.0.1}/LICENSE +0 -0
- {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/__main__.py +0 -0
- {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/cli_utils.py +0 -0
- {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/config_utils.py +0 -0
- {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/data_utils.py +0 -0
- {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/dev_utils.py +0 -0
- {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/file_utils.py +0 -0
- {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/json_utils.py +0 -0
- {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/log_utils.py +0 -0
- {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/py.typed +0 -0
- {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/security_utils.py +0 -0
- {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/string_utils.py +0 -0
- {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/system_utils.py +0 -0
- {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/time_utils.py +0 -0
- {devkitx-1.0.0/src/devtools_py → devkitx-1.0.1/src/devkitx}/validation_utils.py +0 -0
- {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/build-1.3.0.dist-info/licenses/LICENSE +0 -0
- {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/certifi-2025.8.3.dist-info/licenses/LICENSE +0 -0
- {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
- {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/id-1.5.0.dist-info/LICENSE +0 -0
- {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/jaraco.classes-3.4.0.dist-info/LICENSE +0 -0
- {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/jaraco.context-6.0.1.dist-info/LICENSE +0 -0
- {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
- {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/keyring-25.6.0.dist-info/LICENSE +0 -0
- {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
- {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/mdurl-0.1.2.dist-info/LICENSE +0 -0
- {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
- {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/nh3-0.3.0.dist-info/licenses/LICENSE +0 -0
- {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/packaging-25.0.dist-info/licenses/LICENSE +0 -0
- {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
- {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
- {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/readme_renderer-44.0.dist-info/LICENSE +0 -0
- {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
- {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/requests_toolbelt-1.0.0.dist-info/LICENSE +0 -0
- {devkitx-1.0.0 → devkitx-1.0.1}/venv/lib/python3.13/site-packages/rfc3986-2.0.0.dist-info/LICENSE +0 -0
- {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
- {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
|
+
[](https://www.python.org/downloads/)
|
|
67
|
+
[](LICENSE)
|
|
68
|
+
[](https://mypy-lang.org/)
|
|
69
|
+
[](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
|