azrvus-dev-toolkit 0.1.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.
Files changed (45) hide show
  1. azrvus_dev_toolkit-0.1.0.dist-info/METADATA +113 -0
  2. azrvus_dev_toolkit-0.1.0.dist-info/RECORD +45 -0
  3. azrvus_dev_toolkit-0.1.0.dist-info/WHEEL +4 -0
  4. azrvus_dev_toolkit-0.1.0.dist-info/entry_points.txt +2 -0
  5. azrvus_dev_toolkit-0.1.0.dist-info/licenses/LICENSE +21 -0
  6. dev_toolkit/__init__.py +163 -0
  7. dev_toolkit/_version.py +3 -0
  8. dev_toolkit/async_io.py +19 -0
  9. dev_toolkit/banner.py +37 -0
  10. dev_toolkit/cache.py +88 -0
  11. dev_toolkit/cli.py +60 -0
  12. dev_toolkit/cli_formatters.py +79 -0
  13. dev_toolkit/cli_spinner.py +87 -0
  14. dev_toolkit/color.py +34 -0
  15. dev_toolkit/concurrency.py +58 -0
  16. dev_toolkit/config.py +75 -0
  17. dev_toolkit/crypto_utils.py +21 -0
  18. dev_toolkit/decorators.py +47 -0
  19. dev_toolkit/dict_utils.py +77 -0
  20. dev_toolkit/encoding.py +19 -0
  21. dev_toolkit/env.py +23 -0
  22. dev_toolkit/env_validator.py +24 -0
  23. dev_toolkit/events.py +44 -0
  24. dev_toolkit/formatters.py +45 -0
  25. dev_toolkit/hash.py +37 -0
  26. dev_toolkit/http.py +22 -0
  27. dev_toolkit/io.py +40 -0
  28. dev_toolkit/jsonl.py +62 -0
  29. dev_toolkit/logger.py +36 -0
  30. dev_toolkit/masking.py +51 -0
  31. dev_toolkit/pagination.py +29 -0
  32. dev_toolkit/path_utils.py +84 -0
  33. dev_toolkit/process.py +65 -0
  34. dev_toolkit/random_utils.py +19 -0
  35. dev_toolkit/rate_limiter.py +77 -0
  36. dev_toolkit/retry.py +37 -0
  37. dev_toolkit/retry_utils.py +93 -0
  38. dev_toolkit/system.py +24 -0
  39. dev_toolkit/templating.py +28 -0
  40. dev_toolkit/text.py +45 -0
  41. dev_toolkit/timer.py +41 -0
  42. dev_toolkit/transforms.py +21 -0
  43. dev_toolkit/url_utils.py +35 -0
  44. dev_toolkit/validators.py +74 -0
  45. dev_toolkit/watcher.py +66 -0
@@ -0,0 +1,113 @@
1
+ Metadata-Version: 2.5
2
+ Name: azrvus-dev-toolkit
3
+ Version: 0.1.0
4
+ Summary: Dependency-free Python utilities and local JSONL validation for LLM evaluation datasets.
5
+ Project-URL: Homepage, https://github.com/azrvus/dev-toolkit
6
+ Project-URL: Repository, https://github.com/azrvus/dev-toolkit
7
+ Project-URL: Issues, https://github.com/azrvus/dev-toolkit/issues
8
+ Author: azrvus
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: developer-tools,evaluation,jsonl,llm,validation
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3 :: Only
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Requires-Python: >=3.11
19
+ Description-Content-Type: text/markdown
20
+
21
+ # Dev Toolkit
22
+
23
+ [![CI](https://github.com/azrvus/dev-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/azrvus/dev-toolkit/actions)
24
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
25
+
26
+ Published distribution name: `azrvus-dev-toolkit`; Python import: `dev_toolkit`;
27
+ CLI command: `dev-toolkit`.
28
+
29
+ Python 3.11+ utilities with no runtime dependencies. Includes JSON file I/O,
30
+ text helpers, validation, retries, caching, environment checks, and process tools.
31
+
32
+ ## Installation
33
+
34
+ Install from GitHub (verified in a fresh virtual environment):
35
+
36
+ ```bash
37
+ python -m pip install 'git+https://github.com/azrvus/dev-toolkit.git'
38
+ ```
39
+
40
+ Public PyPI installation is pending release verification. Do not use
41
+ `pip install azrvus-dev-toolkit` or `uv add azrvus-dev-toolkit` yet.
42
+
43
+ ## Python examples
44
+
45
+ ```python
46
+ from dev_toolkit import is_email, slugify, read_json, write_json
47
+
48
+ assert slugify("Hello World") == "hello-world"
49
+ assert is_email("user@example.com")
50
+ write_json("example.json", {"status": "ok"})
51
+ assert read_json("example.json") == {"status": "ok"}
52
+ ```
53
+
54
+ `write_json` creates parent directories and refuses to overwrite existing files
55
+ unless `overwrite=True` is passed.
56
+
57
+ ## Command line
58
+
59
+ ```bash
60
+ dev-toolkit --help
61
+ dev-toolkit --version
62
+ dev-toolkit
63
+ dev-toolkit --verbose
64
+ ```
65
+
66
+ With no subcommand, the CLI prints `Dev Toolkit CLI operational.`. With `--verbose`
67
+ (or `-v`), it also prints `Verbose mode enabled.`. Library utilities are used
68
+ through Python imports. The dataset validation subcommand is documented below.
69
+
70
+ ## Development
71
+
72
+ ```bash
73
+ uv venv
74
+ uv pip install -e . pytest ruff
75
+ uv run pytest
76
+ uv run ruff check .
77
+ ```
78
+
79
+ CI runs tests and Ruff on Python 3.11 and 3.12. Test results are checked in CI;
80
+ no coverage percentage is claimed.
81
+
82
+ ## License
83
+
84
+ [MIT](LICENSE).
85
+
86
+ ## Validate LLM evaluation datasets
87
+
88
+ Check local UTF-8 JSONL without sending data anywhere. Each line must be a JSON
89
+ object. Blank lines, empty files, malformed JSON, nonfinite numbers, missing keys,
90
+ and unreadable input are errors. Required keys are top-level; null values count
91
+ as present. Errors include line numbers and never print complete records.
92
+
93
+ ```bash
94
+ dev-toolkit validate-jsonl examples/eval-valid.jsonl --required-key prompt --required-key expected
95
+ # Valid JSONL. (exit 0)
96
+ dev-toolkit validate-jsonl examples/eval-invalid.jsonl --required-key prompt --required-key expected
97
+ # line 1: missing required keys: ['expected']
98
+ # line 2: expected a JSON object
99
+ # exit 1; diagnostics go to stderr
100
+ ```
101
+
102
+ The command checks JSON structure and key presence, not semantic correctness or
103
+ model quality. File-level errors use `file:` instead of a line number.
104
+
105
+ ```python
106
+ from dev_toolkit import validate_jsonl
107
+
108
+ for issue in validate_jsonl("examples/eval-valid.jsonl", required_keys=["prompt"]):
109
+ print(issue.line, issue.message)
110
+ ```
111
+
112
+ The API yields issues lazily and reads one line at a time; consume the iterator
113
+ to perform validation. It retains no records and has no runtime dependencies.
@@ -0,0 +1,45 @@
1
+ dev_toolkit/__init__.py,sha256=XpadBY3MQhENNdvSa9N6nv6f_bZrZZtgo9gDdwC5fg8,4389
2
+ dev_toolkit/_version.py,sha256=1V13oAIl_VHl8HSDh5uhLdsO0ZagOw5EQBB-25wkzME,76
3
+ dev_toolkit/async_io.py,sha256=m3v5MYqjv7ed3G85kEWJSZ41O62AtGMwpAKO0SYoQYI,536
4
+ dev_toolkit/banner.py,sha256=XB_ca1xEzSSUmAE1ZoBeaqhRaMw74nMkt3udJerXfHI,1160
5
+ dev_toolkit/cache.py,sha256=JRVaWqlBHknqNX0yjazTNAkppRwwVIPC-WmbR3h8YWQ,2383
6
+ dev_toolkit/cli.py,sha256=SLTokOmViZ-0CKGGSTgkxJYRWy9qgofm843prKopFMY,1852
7
+ dev_toolkit/cli_formatters.py,sha256=xJ2tYCufBzOf6vzx4JxxOsgvb5aFhepbIpdz9F_go54,2277
8
+ dev_toolkit/cli_spinner.py,sha256=hp2WDaTmqRKpP3jx_bdVDmytwiXA1vUzI_TMCdFUqaQ,2478
9
+ dev_toolkit/color.py,sha256=ODbjH5ke4L5mRekWM4BvHbVdvrqztsACLp8NTae0-14,734
10
+ dev_toolkit/concurrency.py,sha256=MAFhK1ji0BcUZJEJwiQArRojxn3A7QoD52d1D7YF3jA,1940
11
+ dev_toolkit/config.py,sha256=qVpJSaRL-BZkZQynZ2oKMMp8PrI7v-cx-l0tPaxGWxU,2714
12
+ dev_toolkit/crypto_utils.py,sha256=_vOaMHcZ7NI8al_dL0sIFM7sb1QiKAHC-s3SD3mNkO0,552
13
+ dev_toolkit/decorators.py,sha256=eM2OlEdpKC7K40Blphs4lJZUqOqCSqObARvutkKBXpE,1488
14
+ dev_toolkit/dict_utils.py,sha256=qGG_xzVQXcqJjCOO4Osl0JKFLw7WuK3vdT7bNEugam0,2546
15
+ dev_toolkit/encoding.py,sha256=GbrhjfFN1OgDbdZ675KlS679yLEuBUgQALEnvn4-V1Y,540
16
+ dev_toolkit/env.py,sha256=nVAGlGJBfZkpGJsygSoqYOhuywb9MInbNzXyIGd55Eg,831
17
+ dev_toolkit/env_validator.py,sha256=xI4ThOOk2ov6in8b2XKSI9Ep29OPuORDE3fdVfH0KQo,817
18
+ dev_toolkit/events.py,sha256=3QPZ9fynZPoZeSFaSgAW0cXamn3WZxF_3S1D5w5gahg,1557
19
+ dev_toolkit/formatters.py,sha256=7q5bq-jyOdcuJnPz3EGJrr1ynB2I2tQVS2F-n00n30E,1253
20
+ dev_toolkit/hash.py,sha256=wsoHkz_nf7h1tL14Zy2WQayhvRMQczV9HBXKggrUdCM,1069
21
+ dev_toolkit/http.py,sha256=jDxaIV4jKm2dm1NvYcNyNkvP8Ah7I-8q1AjHjhcVoow,603
22
+ dev_toolkit/io.py,sha256=GEvQT7UwkJ6LlF6Mw7Dr-58dquaT1fpPm0998sRF6bg,1183
23
+ dev_toolkit/jsonl.py,sha256=rJwQC8_r9dQLC09UgvvIIKcDvxdfTxW739zkPqRVM7Y,2488
24
+ dev_toolkit/logger.py,sha256=TV10SmOGMOfuiSXWpnn2tKFZwsTy2TU39baych_kX_A,1048
25
+ dev_toolkit/masking.py,sha256=q9IGJcxdjON7gLKmtdrDEWXLuMkFNwzM1L9VG2Q-rws,1954
26
+ dev_toolkit/pagination.py,sha256=ZIS3QdFKwutWlH-ve7afUkhYGYGSJWf1KslX_y0abko,767
27
+ dev_toolkit/path_utils.py,sha256=Kh5SMjJbF3b9XrSwqSImctz5aEwLG-IIMpbiaekwpGs,2824
28
+ dev_toolkit/process.py,sha256=6vUKBow9v8ypN5RZj4kncD8wOAz6lcsJU93N68OFC_g,1641
29
+ dev_toolkit/random_utils.py,sha256=rBSVz2lVgmghpNWkt6b-7RuwwGU9DCYbZfEVx3ZEpA4,459
30
+ dev_toolkit/rate_limiter.py,sha256=aCehKlr0Ub_Mctr_nZiIMYUQ1ySJi5WqnN-ulzSsuNs,2399
31
+ dev_toolkit/retry.py,sha256=k4AvlxRxkdk0vE6nKaBaV7vnrojxUraHMwN-QrM9dQ4,1076
32
+ dev_toolkit/retry_utils.py,sha256=oIB00OnPp-5GGZOzshe02jdVKJYXhJL5vipdWbmHPac,2773
33
+ dev_toolkit/system.py,sha256=MmGYZRvZ2a9LSz7laTj-LSHdlB1YLJAv8egdrSetcPM,744
34
+ dev_toolkit/templating.py,sha256=3bw3veHG9zbaNbJSP1YHpKeQqQDkyZ-i32sfGKjZygI,928
35
+ dev_toolkit/text.py,sha256=YiZcbL98sbSgGpRJtEh_8mh0L9Cj7W7lcHrSqSA5n_w,1572
36
+ dev_toolkit/timer.py,sha256=yx3DE5bgmHFfjdrNO0bS08uOcdKuoqyqGAKxCE4qWe0,1232
37
+ dev_toolkit/transforms.py,sha256=3RSGAORHOnuNT1fnMyMWbyqZe4d6J5t8NO4_lHlnBE4,654
38
+ dev_toolkit/url_utils.py,sha256=6kYn97JLUMB0kgOxZl4AF7fdeUaSh1HeSiq_PgZwFgc,1128
39
+ dev_toolkit/validators.py,sha256=0QHpWPSXTf63h6y5gpS-UP0hOas24Xtl5hhk6YDqeOU,2084
40
+ dev_toolkit/watcher.py,sha256=bfaFrow9EKBW1d9ClORBknPRew5AT2sB2wkipA7WT8I,2073
41
+ azrvus_dev_toolkit-0.1.0.dist-info/METADATA,sha256=ayKaggwkWnZY2tUmLJfYwJ-ZKQQja0sGOpomhJhPAIU,3814
42
+ azrvus_dev_toolkit-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
43
+ azrvus_dev_toolkit-0.1.0.dist-info/entry_points.txt,sha256=FMCFL9iMZb2ZDDMBFbw0-wJ8LSYi80SA1bSBJI72m1k,53
44
+ azrvus_dev_toolkit-0.1.0.dist-info/licenses/LICENSE,sha256=GHU3SisV-ksTtco1yhvzmOGpQogLJDMadkieDydvuDA,1063
45
+ azrvus_dev_toolkit-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ dev-toolkit = dev_toolkit.cli:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 azrvus
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,163 @@
1
+ """Dev Toolkit package initialization."""
2
+
3
+ from dev_toolkit._version import __version__ as __version__
4
+ from dev_toolkit.async_io import read_json_async, write_json_async
5
+ from dev_toolkit.banner import print_banner, print_box, print_divider
6
+ from dev_toolkit.cache import CacheInfo, ttl_cache
7
+ from dev_toolkit.cli import main, parse_args
8
+ from dev_toolkit.cli_formatters import colorize, format_table, progress_bar
9
+ from dev_toolkit.cli_spinner import Spinner
10
+ from dev_toolkit.color import blue, bold, green, red, yellow
11
+ from dev_toolkit.concurrency import run_parallel, run_parallel_processes
12
+ from dev_toolkit.config import ConfigManager
13
+ from dev_toolkit.crypto_utils import generate_token, md5_hash, sha256_hash
14
+ from dev_toolkit.decorators import retry
15
+ from dev_toolkit.dict_utils import (
16
+ chunk_list,
17
+ deep_merge,
18
+ filter_keys,
19
+ flatten_dict,
20
+ get_in,
21
+ omit,
22
+ pick,
23
+ )
24
+ from dev_toolkit.encoding import base64_decode, base64_encode
25
+ from dev_toolkit.env import check_required_env, get_env_summary, mask_secret
26
+ from dev_toolkit.env_validator import get_env_or_raise, validate_env
27
+ from dev_toolkit.events import EventEmitter
28
+ from dev_toolkit.formatters import format_bytes, format_duration
29
+ from dev_toolkit.hash import get_file_hash, get_str_hash
30
+ from dev_toolkit.http import fetch_json
31
+ from dev_toolkit.io import ensure_dir, read_json, write_json
32
+ from dev_toolkit.jsonl import JsonlIssue, validate_jsonl
33
+ from dev_toolkit.logger import get_json_logger
34
+ from dev_toolkit.masking import mask_email, mask_secret_string, sanitize_dict
35
+ from dev_toolkit.pagination import paginate
36
+ from dev_toolkit.path_utils import (
37
+ find_files,
38
+ get_dir_size,
39
+ get_tree,
40
+ replace_extension,
41
+ )
42
+ from dev_toolkit.process import ProcessResult, run_command
43
+ from dev_toolkit.random_utils import generate_uuid, random_string
44
+ from dev_toolkit.rate_limiter import TokenBucket, rate_limit
45
+ from dev_toolkit.retry_utils import retry_with_backoff
46
+ from dev_toolkit.system import get_system_info, print_system_summary
47
+ from dev_toolkit.templating import render_string, render_template_file
48
+ from dev_toolkit.text import (
49
+ camel_to_snake,
50
+ normalize_whitespace,
51
+ sanitize_filename,
52
+ slugify,
53
+ snake_to_camel,
54
+ truncate_words,
55
+ )
56
+ from dev_toolkit.timer import Timer, timed
57
+ from dev_toolkit.transforms import capitalize_words, normalize_spaces, to_snake_case
58
+ from dev_toolkit.url_utils import (
59
+ add_query_params,
60
+ parse_query_params,
61
+ remove_query_params,
62
+ )
63
+ from dev_toolkit.validators import (
64
+ in_range,
65
+ is_email,
66
+ is_ipv4,
67
+ is_ipv6,
68
+ is_url,
69
+ )
70
+ from dev_toolkit.watcher import watch_path
71
+
72
+ __all__ = [
73
+ "CacheInfo",
74
+ "ConfigManager",
75
+ "EventEmitter",
76
+ "JsonlIssue",
77
+ "ProcessResult",
78
+ "Spinner",
79
+ "Timer",
80
+ "TokenBucket",
81
+ "add_query_params",
82
+ "base64_decode",
83
+ "base64_encode",
84
+ "blue",
85
+ "bold",
86
+ "camel_to_snake",
87
+ "capitalize_words",
88
+ "check_required_env",
89
+ "chunk_list",
90
+ "colorize",
91
+ "deep_merge",
92
+ "ensure_dir",
93
+ "fetch_json",
94
+ "filter_keys",
95
+ "find_files",
96
+ "flatten_dict",
97
+ "format_bytes",
98
+ "format_duration",
99
+ "format_table",
100
+ "generate_token",
101
+ "generate_uuid",
102
+ "get_dir_size",
103
+ "get_env_or_raise",
104
+ "get_env_summary",
105
+ "get_file_hash",
106
+ "get_in",
107
+ "get_json_logger",
108
+ "get_str_hash",
109
+ "get_system_info",
110
+ "get_tree",
111
+ "green",
112
+ "in_range",
113
+ "is_email",
114
+ "is_ipv4",
115
+ "is_ipv6",
116
+ "is_url",
117
+ "main",
118
+ "mask_email",
119
+ "mask_secret",
120
+ "mask_secret_string",
121
+ "md5_hash",
122
+ "normalize_spaces",
123
+ "normalize_whitespace",
124
+ "omit",
125
+ "paginate",
126
+ "parse_args",
127
+ "parse_query_params",
128
+ "pick",
129
+ "print_banner",
130
+ "print_box",
131
+ "print_divider",
132
+ "print_system_summary",
133
+ "progress_bar",
134
+ "random_string",
135
+ "rate_limit",
136
+ "read_json",
137
+ "read_json_async",
138
+ "red",
139
+ "remove_query_params",
140
+ "render_string",
141
+ "render_template_file",
142
+ "replace_extension",
143
+ "retry",
144
+ "retry_with_backoff",
145
+ "run_command",
146
+ "run_parallel",
147
+ "run_parallel_processes",
148
+ "sanitize_dict",
149
+ "sanitize_filename",
150
+ "sha256_hash",
151
+ "slugify",
152
+ "snake_to_camel",
153
+ "timed",
154
+ "to_snake_case",
155
+ "truncate_words",
156
+ "ttl_cache",
157
+ "validate_env",
158
+ "validate_jsonl",
159
+ "watch_path",
160
+ "write_json",
161
+ "write_json_async",
162
+ "yellow",
163
+ ]
@@ -0,0 +1,3 @@
1
+ """Single source for the package and CLI version."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,19 @@
1
+ """Asynchronous file I/O utilities."""
2
+
3
+ import asyncio
4
+ from pathlib import Path
5
+ from typing import Any
6
+
7
+ from dev_toolkit.io import read_json, write_json
8
+
9
+
10
+ async def read_json_async(path: str | Path) -> dict[str, Any]:
11
+ """Read and parse a JSON file asynchronously."""
12
+ return await asyncio.to_thread(read_json, path)
13
+
14
+
15
+ async def write_json_async(
16
+ path: str | Path, data: dict[str, Any], indent: int = 2
17
+ ) -> None:
18
+ """Write data to a JSON file asynchronously."""
19
+ await asyncio.to_thread(write_json, path, data, indent)
dev_toolkit/banner.py ADDED
@@ -0,0 +1,37 @@
1
+ from __future__ import annotations
2
+
3
+ __all__ = ["print_banner", "print_box", "print_divider"]
4
+
5
+
6
+ def print_divider(char: str = "-", length: int = 50) -> str:
7
+ """Generate a horizontal divider line."""
8
+ return char * length
9
+
10
+
11
+ def print_box(text: str, padding: int = 2, border_char: str = "#") -> str:
12
+ """Wrap a block of text inside a styled terminal box."""
13
+ lines = text.splitlines() or [text]
14
+ max_len = max(len(line) for line in lines)
15
+ total_width = max_len + (padding * 2)
16
+
17
+ border = border_char * (total_width + 2)
18
+ formatted_lines = [border]
19
+
20
+ for line in lines:
21
+ padded_line = line.ljust(max_len)
22
+ spaces = " " * padding
23
+ formatted_lines.append(
24
+ f"{border_char}{spaces}{padded_line}{spaces}{border_char}"
25
+ )
26
+
27
+ formatted_lines.append(border)
28
+ return "\n".join(formatted_lines)
29
+
30
+
31
+ def print_banner(title: str, subtitle: str | None = None) -> str:
32
+ """Generate a prominent CLI title banner."""
33
+ divider = "=" * (len(title) + 6)
34
+ banner_text = f"\n{divider}\n {title.upper()} \n{divider}"
35
+ if subtitle:
36
+ banner_text += f"\n {subtitle}\n"
37
+ return banner_text
dev_toolkit/cache.py ADDED
@@ -0,0 +1,88 @@
1
+ from __future__ import annotations
2
+
3
+ import time
4
+ from collections import OrderedDict
5
+ from collections.abc import Callable
6
+ from dataclasses import dataclass
7
+ from functools import wraps
8
+ from typing import Any, TypeVar
9
+
10
+ __all__ = ["CacheInfo", "ttl_cache"]
11
+
12
+ F = TypeVar("F", bound=Callable[..., Any])
13
+
14
+
15
+ @dataclass(frozen=True)
16
+ class CacheInfo:
17
+ hits: int
18
+ misses: int
19
+ maxsize: int | None
20
+ currsize: int
21
+
22
+
23
+ @dataclass
24
+ class _CacheEntry:
25
+ value: Any
26
+ expires_at: float
27
+
28
+
29
+ def ttl_cache(ttl: float = 60.0, maxsize: int | None = 128) -> Callable[[F], F]:
30
+ """Decorator to cache function results with a TTL and maxsize (LRU)."""
31
+
32
+ def decorator(func: F) -> F:
33
+ cache: OrderedDict[tuple[Any, ...], _CacheEntry] = OrderedDict()
34
+ hits = 0
35
+ misses = 0
36
+
37
+ @wraps(func)
38
+ def wrapper(*args: Any, **kwargs: Any) -> Any:
39
+ nonlocal hits, misses
40
+
41
+ # Make kwargs hashable by sorting keys
42
+ key = (args, tuple(sorted(kwargs.items())))
43
+ now = time.monotonic()
44
+
45
+ if key in cache:
46
+ entry = cache[key]
47
+ if now < entry.expires_at:
48
+ hits += 1
49
+ cache.move_to_end(key)
50
+ return entry.value
51
+ else:
52
+ # Expired entry
53
+ del cache[key]
54
+
55
+ misses += 1
56
+ result = func(*args, **kwargs)
57
+ expires_at = now + ttl
58
+
59
+ # Evict LRU item if maxsize is reached
60
+ if maxsize is not None and len(cache) >= maxsize > 0:
61
+ cache.popitem(last=False)
62
+
63
+ if maxsize is None or maxsize > 0:
64
+ cache[key] = _CacheEntry(value=result, expires_at=expires_at)
65
+
66
+ return result
67
+
68
+ def cache_info() -> CacheInfo:
69
+ # Clean expired items count check
70
+ return CacheInfo(
71
+ hits=hits,
72
+ misses=misses,
73
+ maxsize=maxsize,
74
+ currsize=len(cache),
75
+ )
76
+
77
+ def cache_clear() -> None:
78
+ nonlocal hits, misses
79
+ cache.clear()
80
+ hits = 0
81
+ misses = 0
82
+
83
+ wrapper.cache_info = cache_info # type: ignore[attr-defined]
84
+ wrapper.cache_clear = cache_clear # type: ignore[attr-defined]
85
+
86
+ return wrapper # type: ignore[return-value]
87
+
88
+ return decorator
dev_toolkit/cli.py ADDED
@@ -0,0 +1,60 @@
1
+ """Command-line interface utilities."""
2
+
3
+ import argparse
4
+ import sys
5
+ from collections.abc import Sequence
6
+
7
+ from dev_toolkit._version import __version__
8
+ from dev_toolkit.jsonl import validate_jsonl
9
+
10
+
11
+ def parse_args(args: Sequence[str] | None = None) -> argparse.Namespace:
12
+ """Parse command-line arguments for dev-toolkit."""
13
+ parser = argparse.ArgumentParser(
14
+ prog="dev-toolkit",
15
+ description="Developer utility toolkit CLI.",
16
+ )
17
+ parser.add_argument(
18
+ "-v",
19
+ "--verbose",
20
+ action="store_true",
21
+ help="enable verbose output",
22
+ )
23
+ parser.add_argument(
24
+ "--version",
25
+ action="version",
26
+ version=f"%(prog)s {__version__}",
27
+ )
28
+ commands = parser.add_subparsers(dest="command")
29
+ validate = commands.add_parser(
30
+ "validate-jsonl", help="validate a local UTF-8 JSONL evaluation dataset"
31
+ )
32
+ validate.add_argument("path", help="path to the dataset")
33
+ validate.add_argument(
34
+ "--required-key", action="append", default=[], metavar="KEY",
35
+ help="require a top-level key (repeat for multiple keys)",
36
+ )
37
+ return parser.parse_args(args)
38
+
39
+
40
+ def main(args: Sequence[str] | None = None) -> int:
41
+ """CLI entrypoint execution."""
42
+ parsed_args = parse_args(args)
43
+ if parsed_args.command == "validate-jsonl":
44
+ invalid = False
45
+ for issue in validate_jsonl(parsed_args.path, parsed_args.required_key):
46
+ invalid = True
47
+ location = f"line {issue.line}" if issue.line else "file"
48
+ print(f"{location}: {issue.message}", file=sys.stderr)
49
+ if invalid:
50
+ return 1
51
+ print("Valid JSONL.")
52
+ return 0
53
+ if parsed_args.verbose:
54
+ print("Verbose mode enabled.")
55
+ print("Dev Toolkit CLI operational.")
56
+ return 0
57
+
58
+
59
+ if __name__ == "__main__":
60
+ sys.exit(main())
@@ -0,0 +1,79 @@
1
+ from __future__ import annotations
2
+
3
+ from typing import Any
4
+
5
+ __all__ = ["colorize", "format_table", "progress_bar"]
6
+
7
+ _COLORS: dict[str, str] = {
8
+ "black": "\033[30m",
9
+ "red": "\033[31m",
10
+ "green": "\033[32m",
11
+ "yellow": "\033[33m",
12
+ "blue": "\033[34m",
13
+ "magenta": "\033[35m",
14
+ "cyan": "\033[36m",
15
+ "white": "\033[37m",
16
+ "reset": "\033[0m",
17
+ }
18
+
19
+
20
+ def colorize(text: str, color: str, bold: bool = False) -> str:
21
+ """Wrap text in ANSI escape codes for colored terminal output."""
22
+ color_code = _COLORS.get(color.lower(), "")
23
+ if not color_code:
24
+ return text
25
+
26
+ bold_code = "\033[1m" if bold else ""
27
+ return f"{bold_code}{color_code}{text}{_COLORS['reset']}"
28
+
29
+
30
+ def progress_bar(
31
+ iteration: int,
32
+ total: int,
33
+ length: int = 30,
34
+ fill: str = "█",
35
+ empty: str = "-",
36
+ ) -> str:
37
+ """Generate a text-based progress bar string."""
38
+ if total <= 0:
39
+ return f"[{empty * length}] 0.0%"
40
+
41
+ percent = min(100.0, max(0.0, (iteration / total) * 100))
42
+ filled_length = int(length * iteration // total)
43
+ filled_length = min(length, max(0, filled_length))
44
+
45
+ bar = fill * filled_length + empty * (length - filled_length)
46
+ return f"[{bar}] {percent:.1f}%"
47
+
48
+
49
+ def format_table(data: list[dict[str, Any]], headers: list[str] | None = None) -> str:
50
+ """Format a list of dictionaries into an ASCII table string."""
51
+ if not data:
52
+ return ""
53
+
54
+ cols = headers if headers else list(data[0].keys())
55
+
56
+ # Calculate max column widths
57
+ col_widths: dict[str, int] = {col: len(str(col)) for col in cols}
58
+ for row in data:
59
+ for col in cols:
60
+ val_str = str(row.get(col, ""))
61
+ col_widths[col] = max(col_widths[col], len(val_str))
62
+
63
+ # Build header row and divider
64
+ header_str = (
65
+ "| " + " | ".join(str(col).ljust(col_widths[col]) for col in cols) + " |"
66
+ )
67
+ divider = "+-" + "-+-".join("-" * col_widths[col] for col in cols) + "-+"
68
+
69
+ # Build data rows
70
+ rows: list[str] = []
71
+ for row in data:
72
+ row_str = (
73
+ "| "
74
+ + " | ".join(str(row.get(col, "")).ljust(col_widths[col]) for col in cols)
75
+ + " |"
76
+ )
77
+ rows.append(row_str)
78
+
79
+ return "\n".join([divider, header_str, divider] + rows + [divider])