stdl 0.8.0__tar.gz → 0.9.0__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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: stdl
3
- Version: 0.8.0
3
+ Version: 0.9.0
4
4
  Summary: Extended Python Standard Library
5
5
  Keywords: stdl,standard-library,python-utilities,filesystem,list-utils,ansi-colors,color-formats,terminal-links,lazy-import,text-processing
6
6
  Author: Žiga Ivanšek
@@ -30,11 +30,9 @@ Requires-Dist: anyio>=4.0.0 ; extra == 'dev'
30
30
  Requires-Dist: pytest>=9.0.3 ; extra == 'dev'
31
31
  Requires-Dist: coverage>=7.14.1 ; extra == 'dev'
32
32
  Requires-Dist: ruff==0.16.10 ; extra == 'dev'
33
- Requires-Dist: pre-commit>=4.6.0 ; extra == 'dev'
34
33
  Requires-Dist: pyrefly>=1.0.0 ; extra == 'dev'
35
- Requires-Dist: codespell>=2.4.2 ; extra == 'dev'
36
34
  Requires-Dist: pydantic>=2 ; extra == 'dev'
37
- Requires-Dist: rattle-lint>=3.0.0 ; extra == 'dev'
35
+ Requires-Dist: rattle-lint>=3.4.0 ; extra == 'dev'
38
36
  Requires-Dist: tqdm>=4.67.1 ; extra == 'full'
39
37
  Requires-Dist: anyio>=4.0.0 ; extra == 'test'
40
38
  Requires-Dist: pytest>=9.0.3 ; extra == 'test'
@@ -52,12 +50,13 @@ Description-Content-Type: text/markdown
52
50
 
53
51
  # stdl
54
52
 
55
- [![Tests](https://github.com/zigai/stdl/actions/workflows/test.yml/badge.svg)](https://github.com/zigai/stdl/actions/workflows/test.yml)
56
- [![Documentation Status](https://readthedocs.org/projects/stdl/badge/?version=latest)](https://stdl.readthedocs.io/en/latest/?badge=latest)
57
- [![PyPI version](https://badge.fury.io/py/stdl.svg)](https://badge.fury.io/py/stdl)
58
- ![Supported versions](https://img.shields.io/badge/python-3.11+-blue.svg)
59
- [![Downloads](https://static.pepy.tech/badge/stdl)](https://pepy.tech/project/stdl)
60
- [![license](https://img.shields.io/github/license/zigai/stdl.svg)](https://github.com/zigai/stdl/blob/master/LICENSE)
53
+ [![tests](https://img.shields.io/github/actions/workflow/status/zigai/stdl/test.yml?branch=master&label=tests&labelColor=30363d)](https://github.com/zigai/stdl/actions/workflows/test.yml)
54
+ [![docs](https://img.shields.io/readthedocs/stdl?label=docs&logo=readthedocs&logoColor=white&labelColor=30363d)](https://stdl.readthedocs.io/en/latest/)
55
+ [![PyPI](https://img.shields.io/pypi/v/stdl?label=PyPI&color=blue&logo=pypi&logoColor=white&labelColor=30363d)](https://pypi.org/project/stdl/)
56
+ [![Python](https://img.shields.io/badge/Python-3.11+-blue?logo=python&logoColor=white&labelColor=30363d)](pyproject.toml)
57
+ [![downloads](https://img.shields.io/pypi/dm/stdl?label=downloads&color=blue&labelColor=30363d)](https://pepy.tech/projects/stdl)
58
+ [![downloads](https://img.shields.io/pepy/dt/stdl?label=downloads&color=blue&labelColor=30363d)](https://pepy.tech/projects/stdl)
59
+ [![license](https://img.shields.io/github/license/zigai/stdl?label=license&labelColor=30363d)](LICENSE)
61
60
 
62
61
  `stdl` is a collection of Python utilities that complement the standard library.
63
62
 
stdl-0.9.0/README.md ADDED
@@ -0,0 +1,50 @@
1
+ # stdl
2
+
3
+ [![tests](https://img.shields.io/github/actions/workflow/status/zigai/stdl/test.yml?branch=master&label=tests&labelColor=30363d)](https://github.com/zigai/stdl/actions/workflows/test.yml)
4
+ [![docs](https://img.shields.io/readthedocs/stdl?label=docs&logo=readthedocs&logoColor=white&labelColor=30363d)](https://stdl.readthedocs.io/en/latest/)
5
+ [![PyPI](https://img.shields.io/pypi/v/stdl?label=PyPI&color=blue&logo=pypi&logoColor=white&labelColor=30363d)](https://pypi.org/project/stdl/)
6
+ [![Python](https://img.shields.io/badge/Python-3.11+-blue?logo=python&logoColor=white&labelColor=30363d)](pyproject.toml)
7
+ [![downloads](https://img.shields.io/pypi/dm/stdl?label=downloads&color=blue&labelColor=30363d)](https://pepy.tech/projects/stdl)
8
+ [![downloads](https://img.shields.io/pepy/dt/stdl?label=downloads&color=blue&labelColor=30363d)](https://pepy.tech/projects/stdl)
9
+ [![license](https://img.shields.io/github/license/zigai/stdl?label=license&labelColor=30363d)](LICENSE)
10
+
11
+ `stdl` is a collection of Python utilities that complement the standard library.
12
+
13
+ ## Features
14
+
15
+ - File and directory operations
16
+ - String manipulation
17
+ - ANSI color support for terminal output
18
+ - Date and time formatting
19
+ - List utils
20
+ - Lazy imports
21
+ - Logging configuration for `logging` and `loguru`
22
+ - [See docs](https://stdl.readthedocs.io/en/latest/?badge=latest)
23
+
24
+ ## Installation
25
+
26
+ ### Using pip
27
+
28
+ ```sh
29
+ pip install stdl
30
+ pip install 'stdl[async]'
31
+ ```
32
+
33
+ ### Using uv
34
+
35
+ ```sh
36
+ uv add stdl
37
+ uv add 'stdl[async]'
38
+ ```
39
+
40
+ ### From source
41
+
42
+ ```sh
43
+ pip install git+https://github.com/zigai/stdl.git
44
+ # or
45
+ uv add git+https://github.com/zigai/stdl.git
46
+ ```
47
+
48
+ ## License
49
+
50
+ [MIT License](https://github.com/zigai/stdl/blob/master/LICENSE)
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "stdl"
3
- version = "0.8.0"
3
+ version = "0.9.0"
4
4
  description = "Extended Python Standard Library"
5
5
  license = "MIT"
6
6
  license-files = ["LICENSE"]
@@ -53,11 +53,9 @@ dev = [
53
53
  "pytest>=9.0.3",
54
54
  "coverage>=7.14.1",
55
55
  "ruff==0.16.10",
56
- "pre-commit>=4.6.0",
57
56
  "pyrefly>=1.0.0",
58
- "codespell>=2.4.2",
59
57
  "pydantic>=2",
60
- "rattle-lint>=3.0.0",
58
+ "rattle-lint>=3.4.0",
61
59
  ]
62
60
  test = [
63
61
  "anyio>=4.0.0",
@@ -75,12 +73,11 @@ Homepage = "https://github.com/zigai/stdl"
75
73
  requires = ["uv_build>=0.11.25,<0.12.0"]
76
74
  build-backend = "uv_build"
77
75
 
78
- [tool.codespell]
79
- skip = ".git,uv.lock"
80
-
81
76
  [tool.coverage.run]
82
77
  source = ["stdl"]
83
78
  branch = true
79
+ parallel = true
80
+ patch = ["subprocess"]
84
81
 
85
82
  [tool.coverage.report]
86
83
  exclude_lines = [
@@ -275,26 +272,27 @@ quote-style = "double"
275
272
  indent-style = "space"
276
273
  skip-magic-trailing-comma = false
277
274
  line-ending = "lf"
275
+ exclude = []
278
276
 
279
277
  [tool.uv]
280
- default-groups = ["test"]
278
+ default-groups = ["dev"]
281
279
 
282
280
  [tool.uv.build-backend]
283
281
  module-name = "stdl"
284
282
  module-root = ""
285
283
 
286
284
  [dependency-groups]
287
- test = [
285
+ dev = [
288
286
  "anyio>=4.0.0",
289
287
  "pytest>=9.0.3",
290
288
  "coverage>=7.14.1",
291
289
  "pydantic>=2",
292
- ]
293
- dev = [
294
- { include-group = "test" },
295
290
  "ruff==0.16.10",
296
- "pre-commit>=4.6.0",
297
291
  "pyrefly>=1.0.0",
298
- "codespell>=2.4.2",
299
- "rattle-lint>=3.0.0",
292
+ "rattle-lint>=3.4.0",
293
+ "tqdm>=4.67.1",
294
+ "types-python-dateutil",
295
+ "types-PyYAML",
296
+ "types-toml",
297
+ "types-tqdm",
300
298
  ]
@@ -1,17 +1,13 @@
1
1
  [project]
2
2
  name = "stdl"
3
- version = "0.8.0"
3
+ version = "0.9.0"
4
4
  description = "Extended Python Standard Library"
5
5
  authors = [{ name = "Žiga Ivanšek", email = "ziga.ivansek@gmail.com" }]
6
6
  license = "MIT"
7
7
  license-files = ["LICENSE"]
8
8
  readme = "README.md"
9
9
  requires-python = ">=3.11"
10
- dependencies = [
11
- "python-dateutil>=2.8.2",
12
- "pyyaml>=6.0.2",
13
- "toml>=0.10.2",
14
- ]
10
+ dependencies = ["python-dateutil>=2.8.2", "pyyaml>=6.0.2", "toml>=0.10.2"]
15
11
 
16
12
  classifiers = [
17
13
  "Typing :: Typed",
@@ -52,11 +48,9 @@ dev = [
52
48
  "pytest>=9.0.3",
53
49
  "coverage>=7.14.1",
54
50
  "ruff==0.16.10",
55
- "pre-commit>=4.6.0",
56
51
  "pyrefly>=1.0.0",
57
- "codespell>=2.4.2",
58
52
  "pydantic>=2",
59
- "rattle-lint>=3.0.0",
53
+ "rattle-lint>=3.4.0",
60
54
  ]
61
55
 
62
56
  test = ["anyio>=4.0.0", "pytest>=9.0.3", "coverage>=7.14.1", "pydantic>=2"]
@@ -73,12 +67,11 @@ build-backend = "uv_build"
73
67
  module-name = "stdl"
74
68
  module-root = ""
75
69
 
76
- [tool.codespell]
77
- skip = '.git,uv.lock'
78
-
79
70
  [tool.coverage.run]
80
71
  source = ["stdl"]
81
72
  branch = true
73
+ parallel = true
74
+ patch = ["subprocess"]
82
75
 
83
76
  [tool.coverage.report]
84
77
  exclude_lines = [
@@ -234,27 +227,20 @@ exclude = ["build"]
234
227
  "examples/*.py" = ["INP001"]
235
228
 
236
229
  [tool.ruff.lint.pep8-naming]
237
- classmethod-decorators = [
238
- "pydantic.validator",
239
- "declared_attr",
240
- "expression",
241
- "comparator",
242
- ]
230
+ classmethod-decorators = ["pydantic.validator", "declared_attr", "expression", "comparator"]
243
231
 
244
232
  [tool.ruff.lint.flake8-builtins]
245
233
  ignorelist = ["id", "input"]
246
234
 
247
235
  [tool.ruff.lint.flake8-type-checking]
248
- runtime-evaluated-base-classes = [
249
- "pydantic.BaseModel",
250
- "sqlalchemy.orm.DeclarativeBase",
251
- ]
236
+ runtime-evaluated-base-classes = ["pydantic.BaseModel", "sqlalchemy.orm.DeclarativeBase"]
252
237
 
253
238
  [tool.ruff.format]
254
239
  quote-style = "double"
255
240
  indent-style = "space"
256
241
  skip-magic-trailing-comma = false
257
242
  line-ending = "lf"
243
+ exclude = []
258
244
 
259
245
  [tool.ruff.lint.isort]
260
246
  known-first-party = ["stdl", "tests"]
@@ -263,8 +249,20 @@ known-first-party = ["stdl", "tests"]
263
249
  convention = "google"
264
250
 
265
251
  [tool.uv]
266
- default-groups = ["test"]
252
+ default-groups = ["dev"]
267
253
 
268
254
  [dependency-groups]
269
- test = ["anyio>=4.0.0", "pytest>=9.0.3", "coverage>=7.14.1", "pydantic>=2"]
270
- dev = [{include-group = "test"}, "ruff==0.16.10", "pre-commit>=4.6.0", "pyrefly>=1.0.0", "codespell>=2.4.2", "rattle-lint>=3.0.0"]
255
+ dev = [
256
+ "anyio>=4.0.0",
257
+ "pytest>=9.0.3",
258
+ "coverage>=7.14.1",
259
+ "pydantic>=2",
260
+ "ruff==0.16.10",
261
+ "pyrefly>=1.0.0",
262
+ "rattle-lint>=3.4.0",
263
+ "tqdm>=4.67.1",
264
+ "types-python-dateutil",
265
+ "types-PyYAML",
266
+ "types-toml",
267
+ "types-tqdm",
268
+ ]
@@ -137,7 +137,7 @@ class RGB(Color):
137
137
  def __repr__(self) -> str:
138
138
  return f"rgb({self.red}, {self.green}, {self.blue})"
139
139
 
140
- def __eq__(self, other: RGB) -> bool:
140
+ def __eq__(self, other: object) -> bool:
141
141
  if not isinstance(other, RGB):
142
142
  return NotImplemented
143
143
 
@@ -237,7 +237,7 @@ class RGBA(Color):
237
237
  def __repr__(self) -> str:
238
238
  return f"rgba({self.red}, {self.green}, {self.blue}, {self.alpha})"
239
239
 
240
- def __eq__(self, other: RGBA) -> bool:
240
+ def __eq__(self, other: object) -> bool:
241
241
  if not isinstance(other, RGBA):
242
242
  return NotImplemented
243
243
 
@@ -322,7 +322,7 @@ class HEX(Color):
322
322
  def __repr__(self) -> str:
323
323
  return f"hex({self.value})"
324
324
 
325
- def __eq__(self, other: HEX) -> bool:
325
+ def __eq__(self, other: object) -> bool:
326
326
  if not isinstance(other, HEX):
327
327
  return NotImplemented
328
328
 
@@ -384,7 +384,7 @@ class HSV(Color):
384
384
  def to_str(self) -> str:
385
385
  return f"hsv({self.hue}°, {self.saturation}%, {self.value}%)"
386
386
 
387
- def __eq__(self, other: HSV) -> bool:
387
+ def __eq__(self, other: object) -> bool:
388
388
  if not isinstance(other, HSV):
389
389
  return NotImplemented
390
390
 
@@ -466,7 +466,7 @@ class HSL(Color):
466
466
  def to_str(self) -> str:
467
467
  return f"hsl({self.hue}°, {self.saturation}%, {self.lightness}%)"
468
468
 
469
- def __eq__(self, other: HSL) -> bool:
469
+ def __eq__(self, other: object) -> bool:
470
470
  if not isinstance(other, HSL):
471
471
  return NotImplemented
472
472
 
@@ -563,7 +563,7 @@ class CMYK(Color):
563
563
  def to_str(self) -> str:
564
564
  return f"cmyk({self.cyan}%, {self.magenta}%, {self.yellow}%, {self.key}%)"
565
565
 
566
- def __eq__(self, other: CMYK) -> bool:
566
+ def __eq__(self, other: object) -> bool:
567
567
  if not isinstance(other, CMYK):
568
568
  return NotImplemented
569
569
 
@@ -633,7 +633,7 @@ class ASSA(Color):
633
633
  def to_str(self) -> str:
634
634
  return self.value
635
635
 
636
- def __eq__(self, other: ASSA) -> bool:
636
+ def __eq__(self, other: object) -> bool:
637
637
  if not isinstance(other, ASSA):
638
638
  return NotImplemented
639
639
 
@@ -936,7 +936,7 @@ CssColorName = T.Literal[
936
936
  "yellowgreen",
937
937
  ]
938
938
 
939
- CSS_COLOR_TO_HEX = {
939
+ CSS_COLOR_TO_HEX: dict[CssColorName, str] = {
940
940
  "aliceblue": "#F0F8FF",
941
941
  "antiquewhite": "#FAEBD7",
942
942
  "aqua": "#00FFFF",
@@ -1088,16 +1088,28 @@ CSS_COLOR_TO_HEX = {
1088
1088
  }
1089
1089
 
1090
1090
 
1091
+ def _is_css_color_name(name: str) -> T.TypeGuard[CssColorName]:
1092
+ return name in CSS_COLOR_TO_HEX
1093
+
1094
+
1095
+ def _css_color_name(name: str) -> CssColorName:
1096
+ name = name.lower()
1097
+ if not _is_css_color_name(name):
1098
+ raise ColorValueError(f"Unknown web color name '{name}'")
1099
+
1100
+ return name
1101
+
1102
+
1091
1103
  class WebColor(Color):
1092
1104
  __slots__ = ("hex_value", "name")
1093
- name: str
1105
+ name: CssColorName
1094
1106
  hex_value: HEX
1095
1107
  COLORS = CSS_COLOR_TO_HEX
1096
1108
 
1097
1109
  def __init__(self, name: CssColorName) -> None:
1098
1110
  super().__init__()
1099
1111
 
1100
- self.name = name.lower()
1112
+ self.name = _css_color_name(name)
1101
1113
  self.validate()
1102
1114
  self.hex_value = HEX(self.COLORS[self.name])
1103
1115
  self._freeze()
@@ -1112,7 +1124,7 @@ class WebColor(Color):
1112
1124
  def __repr__(self) -> str:
1113
1125
  return f"webcolor('{self.name}')"
1114
1126
 
1115
- def __eq__(self, other: WebColor) -> bool:
1127
+ def __eq__(self, other: object) -> bool:
1116
1128
  if not isinstance(other, WebColor):
1117
1129
  return NotImplemented
1118
1130
 
@@ -1186,9 +1198,11 @@ def normalize_color(
1186
1198
  and all(isinstance(x, (int, float)) and not isinstance(x, bool) for x in color)
1187
1199
  ):
1188
1200
  if len(color) == 3:
1189
- return RGB(*color)
1201
+ red, green, blue = (_coerce_rgb_channel(channel) for channel in color)
1202
+ return RGB(red, green, blue)
1190
1203
  if len(color) == 4:
1191
- return RGBA(*color)
1204
+ red, green, blue = (_coerce_rgb_channel(channel) for channel in color[:3])
1205
+ return RGBA(red, green, blue, color[3])
1192
1206
 
1193
1207
  raise ColorValueError(f"Invalid sequence length: {len(color)}")
1194
1208
 
@@ -1198,7 +1212,7 @@ def normalize_color(
1198
1212
  if color.startswith(("&h", "&H")):
1199
1213
  return ASSA.from_value(color)
1200
1214
 
1201
- return WebColor(color)
1215
+ return WebColor(_css_color_name(color))
1202
1216
 
1203
1217
  raise ColorValueError(f"Unsupported color format: {color}")
1204
1218
 
@@ -1362,7 +1376,7 @@ if _HAS_PYDANTIC:
1362
1376
  def parse_assa(value: str | Mapping[str, T.Any]) -> ASSA:
1363
1377
  if isinstance(value, Mapping):
1364
1378
  data = _matching_mapping(value, ({"value"}, {"clean_value"}), label="ASSA")
1365
- return ASSA(data.get("value", data.get("clean_value")))
1379
+ return ASSA(data["value"] if "value" in data else data["clean_value"])
1366
1380
 
1367
1381
  match = re.fullmatch(r"\s*assa\(\s*([0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})\s*\)\s*", value)
1368
1382
  if not match:
@@ -1373,13 +1387,13 @@ if _HAS_PYDANTIC:
1373
1387
  def parse_webcolor(value: str | Mapping[str, T.Any]) -> WebColor:
1374
1388
  if isinstance(value, Mapping):
1375
1389
  data = _exact_mapping(value, {"name"}, label="webcolor")
1376
- return WebColor(data["name"])
1390
+ return WebColor(_css_color_name(data["name"]))
1377
1391
 
1378
1392
  match = re.fullmatch(r"\s*webcolor\(\s*(['\"])\s*([A-Za-z]+)\s*\1\s*\)\s*", value)
1379
1393
  if not match:
1380
1394
  raise ValueError(f"Invalid webcolor repr: {value!r}")
1381
1395
 
1382
- return WebColor(match.group(2))
1396
+ return WebColor(_css_color_name(match.group(2)))
1383
1397
 
1384
1398
  def _string_schema(
1385
1399
  *,
@@ -13,7 +13,7 @@ T = TypeVar("T")
13
13
 
14
14
  def timer(
15
15
  r: int | None = 2,
16
- sink: Callable[[str], None] = sys.stdout.write,
16
+ sink: Callable[[str], object] = sys.stdout.write,
17
17
  show_args: bool = False,
18
18
  serialize: bool = False,
19
19
  sep: str = " | ",
@@ -3,16 +3,22 @@ import time
3
3
  import warnings
4
4
  from collections.abc import Generator
5
5
  from dataclasses import dataclass
6
- from datetime import date, datetime, timedelta, timezone, tzinfo
6
+ from datetime import UTC, date, datetime, timedelta, timezone, tzinfo
7
+
8
+
9
+ def parse_datetime_str(timestr: str) -> datetime:
10
+ """Parse a date/time string with `dateutil.parser.parse`."""
11
+ with warnings.catch_warnings():
12
+ warnings.filterwarnings(
13
+ "ignore",
14
+ message=r"datetime\.datetime\.utcfromtimestamp\(\) is deprecated.*",
15
+ category=DeprecationWarning,
16
+ module=r"dateutil\.tz\.tz",
17
+ )
18
+ from dateutil.parser import parse
19
+
20
+ return parse(timestr)
7
21
 
8
- with warnings.catch_warnings():
9
- warnings.filterwarnings(
10
- "ignore",
11
- message=r"datetime\.datetime\.utcfromtimestamp\(\) is deprecated.*",
12
- category=DeprecationWarning,
13
- module=r"dateutil\.tz\.tz",
14
- )
15
- from dateutil.parser import parse as parse_datetime_str
16
22
 
17
23
  local_timezone: tzinfo | None = datetime.now().astimezone().tzinfo
18
24
  DATE_FMT_CHARS = frozenset("Ymd")
@@ -141,12 +147,12 @@ def datetime_fmt(
141
147
  ```
142
148
  """
143
149
  if d is None:
144
- d = datetime.fromtimestamp(time.time(), tz=timezone.utc if utc else None)
150
+ d = datetime.fromtimestamp(time.time(), tz=UTC if utc else None)
145
151
 
146
152
  elif isinstance(d, str):
147
153
  d = parse_datetime_str(d)
148
154
  elif isinstance(d, (float, int)):
149
- d = datetime.fromtimestamp(d, tz=timezone.utc if utc else None)
155
+ d = datetime.fromtimestamp(d, tz=UTC if utc else None)
150
156
  elif isinstance(d, datetime):
151
157
  pass
152
158
  else:
@@ -180,11 +186,11 @@ def time_fmt(
180
186
  str: Formatted time.
181
187
  """
182
188
  if t is None:
183
- tm = datetime.fromtimestamp(time.time(), tz=timezone.utc if utc else None)
189
+ tm = datetime.fromtimestamp(time.time(), tz=UTC if utc else None)
184
190
  elif isinstance(t, datetime):
185
191
  tm = t.time()
186
192
  elif isinstance(t, (int, float)):
187
- tm = datetime.fromtimestamp(t, tz=timezone.utc if utc else None)
193
+ tm = datetime.fromtimestamp(t, tz=UTC if utc else None)
188
194
  else:
189
195
  raise TypeError(type(t))
190
196
  ts = tm.strftime(f"%H{sep}%M{sep}%S")
@@ -227,9 +233,9 @@ def date_fmt(
227
233
  ```
228
234
  """
229
235
  if d is None:
230
- d = datetime.fromtimestamp(time.time(), tz=timezone.utc).astimezone().date()
236
+ d = datetime.fromtimestamp(time.time(), tz=UTC).astimezone().date()
231
237
  elif isinstance(d, (float, int)):
232
- d = datetime.fromtimestamp(d, tz=timezone.utc).astimezone().date()
238
+ d = datetime.fromtimestamp(d, tz=UTC).astimezone().date()
233
239
  elif isinstance(d, datetime):
234
240
  d = d.date()
235
241
  elif isinstance(d, date):
@@ -253,7 +259,7 @@ def date_range(start: date, end: date) -> Generator[date, None, None]:
253
259
  2022-11-21
254
260
  ```
255
261
  """
256
- for n in range(int((end - start).days)):
262
+ for n in range((end - start).days):
257
263
  yield start + timedelta(n)
258
264
 
259
265
 
@@ -19,6 +19,7 @@ from collections.abc import (
19
19
  AsyncIterator,
20
20
  Awaitable,
21
21
  Callable,
22
+ Collection,
22
23
  Generator,
23
24
  Iterable,
24
25
  Iterator,
@@ -39,13 +40,12 @@ from typing import (
39
40
  Protocol,
40
41
  Self,
41
42
  TypeAlias,
43
+ TypedDict,
44
+ TypeGuard,
42
45
  TypeVar,
46
+ Unpack,
43
47
  overload,
44
48
  )
45
- from urllib.request import pathname2url
46
-
47
- import toml
48
- import yaml
49
49
 
50
50
  from stdl import st
51
51
 
@@ -92,14 +92,37 @@ YamlValue: TypeAlias = (
92
92
  | dict["YamlValue", "YamlValue"]
93
93
  | None
94
94
  )
95
- OpenKwarg: TypeAlias = str | int | bool | Callable[[str, int], int] | None
96
- SubprocessRunArg: TypeAlias = str | bytes | int | bool | float | None
97
- SubprocessRunKwarg: TypeAlias = (
98
- str | bytes | int | bool | float | IO[str] | IO[bytes] | list[str] | dict[str, str] | None
99
- )
100
95
  DirectoryIdentity: TypeAlias = tuple[Literal["inode"], int, int] | tuple[Literal["path"], str]
101
96
 
102
97
 
98
+ class OpenOptions(TypedDict, total=False):
99
+ buffering: int
100
+ errors: str | None
101
+ newline: str | None
102
+ closefd: bool
103
+ opener: Callable[[str, int], int] | None
104
+
105
+
106
+ class SubprocessRunOptions(TypedDict, total=False):
107
+ bufsize: int
108
+ executable: str | bytes | PathLike[str] | PathLike[bytes] | None
109
+ preexec_fn: Callable[[], object] | None
110
+ close_fds: bool
111
+ universal_newlines: bool | None
112
+ creationflags: int
113
+ restore_signals: bool
114
+ start_new_session: bool
115
+ pass_fds: Collection[int]
116
+ encoding: str | None
117
+ errors: str | None
118
+ user: int | str | None
119
+ group: int | str | None
120
+ extra_groups: Iterable[int | str] | None
121
+ umask: int
122
+ pipesize: int
123
+ process_group: int | None
124
+
125
+
103
126
  class AsyncLock(Protocol):
104
127
  async def __aenter__(self) -> Self: ...
105
128
 
@@ -199,7 +222,7 @@ class AnyIOModule(Protocol):
199
222
  file: str | PathLike[str],
200
223
  mode: str = "r",
201
224
  encoding: str | None = None,
202
- **kwargs: OpenKwarg,
225
+ **kwargs: Unpack[OpenOptions],
203
226
  ) -> AsyncFileLike[str] | AsyncFileLike[bytes]: ...
204
227
 
205
228
 
@@ -220,20 +243,27 @@ _ANYIO: AnyIOModule | None = None
220
243
  _ITERATION_SENTINEL = IterationSentinel()
221
244
 
222
245
 
246
+ _ANYIO_REQUIRED_ATTRIBUTES = (
247
+ "to_thread",
248
+ "CancelScope",
249
+ "Lock",
250
+ "Semaphore",
251
+ "create_task_group",
252
+ "get_cancelled_exc_class",
253
+ "open_file",
254
+ )
255
+
256
+
257
+ def _is_anyio_module(module: ModuleType) -> TypeGuard[AnyIOModule]:
258
+ return all(hasattr(module, name) for name in _ANYIO_REQUIRED_ATTRIBUTES)
259
+
260
+
223
261
  def _validate_anyio_module(module: ModuleType) -> AnyIOModule:
224
- for name in (
225
- "to_thread",
226
- "CancelScope",
227
- "Lock",
228
- "Semaphore",
229
- "create_task_group",
230
- "get_cancelled_exc_class",
231
- "open_file",
232
- ):
233
- if not hasattr(module, name):
234
- raise ImportError(f"AnyIO module is missing required attribute {name!r}")
262
+ if _is_anyio_module(module):
263
+ return module
235
264
 
236
- return module
265
+ missing = next(name for name in _ANYIO_REQUIRED_ATTRIBUTES if not hasattr(module, name))
266
+ raise ImportError(f"AnyIO module is missing required attribute {missing!r}")
237
267
 
238
268
 
239
269
  def _load_anyio() -> AnyIOModule:
@@ -276,7 +306,7 @@ async def iterate_fs(iterable_factory: Callable[[], Iterable[T]]) -> AsyncGenera
276
306
  try:
277
307
  while True:
278
308
  item = await run_fs_sync(_next_or_sentinel, iterator)
279
- if item is _ITERATION_SENTINEL:
309
+ if isinstance(item, IterationSentinel):
280
310
  return
281
311
 
282
312
  yield item
@@ -368,6 +398,12 @@ async def _run_limited_map_worker(
368
398
 
369
399
 
370
400
  class AsyncFileHandle(Generic[HandleDataT]):
401
+ @overload
402
+ def __init__(self: AsyncFileHandle[str], handle: AsyncFileLike[str]) -> None: ...
403
+
404
+ @overload
405
+ def __init__(self: AsyncFileHandle[bytes], handle: AsyncFileLike[bytes]) -> None: ...
406
+
371
407
  def __init__(self, handle: AsyncFileLike[HandleDataT]) -> None:
372
408
  self._handle: AsyncFileLike[HandleDataT] = handle
373
409
  self._lock: AsyncLock | None = None
@@ -536,6 +572,33 @@ def _is_same_filesystem_path(path: str | PathLike, other: str | PathLike) -> boo
536
572
  )
537
573
 
538
574
 
575
+ @overload
576
+ def _clone_with_path(
577
+ path_object: File,
578
+ path: str | PathLike,
579
+ *,
580
+ abs: bool = False,
581
+ ) -> File: ...
582
+
583
+
584
+ @overload
585
+ def _clone_with_path(
586
+ path_object: Directory,
587
+ path: str | PathLike,
588
+ *,
589
+ abs: bool = False,
590
+ ) -> Directory: ...
591
+
592
+
593
+ @overload
594
+ def _clone_with_path(
595
+ path_object: PathBase,
596
+ path: str | PathLike,
597
+ *,
598
+ abs: bool = False,
599
+ ) -> PathBase: ...
600
+
601
+
539
602
  def _clone_with_path(
540
603
  path_object: PathBase,
541
604
  path: str | PathLike,
@@ -664,13 +727,13 @@ def _replace_temp_path(temp_path: str, destination_path: str, *, overwrite: bool
664
727
  os.replace(temp_path, destination_path)
665
728
 
666
729
 
667
- def pickle_load(filepath: str | PathLike) -> PickleDataT:
730
+ def pickle_load(filepath: str | PathLike) -> object:
668
731
  """Loads a pickled file."""
669
732
  with open(filepath, "rb") as f:
670
733
  return pickle.load(f) # noqa: S301
671
734
 
672
735
 
673
- async def pickle_load_async(filepath: str | PathLike) -> PickleDataT:
736
+ async def pickle_load_async(filepath: str | PathLike) -> object:
674
737
  """Async version of pickle_load()."""
675
738
  return await run_fs_sync(pickle_load, filepath)
676
739
 
@@ -819,6 +882,8 @@ def yaml_load(
819
882
  Returns:
820
883
  dict | list[dict]: The YAML data loaded from the file.
821
884
  """
885
+ import yaml
886
+
822
887
  with open(path, encoding=encoding) as f:
823
888
  return yaml.safe_load(f)
824
889
 
@@ -839,6 +904,8 @@ def yaml_dump(data: YamlValue, path: str | PathLike, encoding: str = "utf-8") ->
839
904
  path (Pathlike): path to the output file
840
905
  encoding (str): encoding of the output file. Default: 'utf-8'
841
906
  """
907
+ import yaml
908
+
842
909
  with open(path, "w", encoding=encoding) as f:
843
910
  yaml.safe_dump(data, f)
844
911
 
@@ -849,6 +916,8 @@ async def yaml_dump_async(data: YamlValue, path: str | PathLike, encoding: str =
849
916
 
850
917
 
851
918
  def toml_load(path: str | PathLike, encoding: str = "utf-8") -> dict[str, Any]:
919
+ import toml
920
+
852
921
  with open(path, encoding=encoding) as f:
853
922
  return toml.load(f)
854
923
 
@@ -859,6 +928,8 @@ async def toml_load_async(path: str | PathLike, encoding: str = "utf-8") -> dict
859
928
 
860
929
 
861
930
  def toml_dump(data: dict[str, Any], path: str | PathLike, encoding: str = "utf-8") -> None:
931
+ import toml
932
+
862
933
  with open(path, "w", encoding=encoding) as f:
863
934
  toml.dump(data, f)
864
935
 
@@ -1292,8 +1363,7 @@ def exec_cmd(
1292
1363
  input: str | bytes | None = None,
1293
1364
  env: dict[str, str] | None = None,
1294
1365
  text: bool = True,
1295
- *args: SubprocessRunArg,
1296
- **kwargs: SubprocessRunKwarg,
1366
+ **kwargs: Unpack[SubprocessRunOptions],
1297
1367
  ) -> CompletedCommand:
1298
1368
  """
1299
1369
  Wrapper for subprocess.run with nicer default arguments.
@@ -1311,7 +1381,6 @@ def exec_cmd(
1311
1381
  input (str | bytes): input to send to the command.
1312
1382
  env (dict, optional): environment variables to pass to the new process.
1313
1383
  text (bool): whether or not to return output as text or bytes.
1314
- *args : additional arguments to pass to subprocess.run.
1315
1384
  **kwargs : additional keyword arguments to pass to subprocess.run.
1316
1385
 
1317
1386
  Returns:
@@ -1324,7 +1393,6 @@ def exec_cmd(
1324
1393
 
1325
1394
  result = subprocess.run( # noqa: S603
1326
1395
  cmd,
1327
- *args,
1328
1396
  timeout=timeout,
1329
1397
  shell=shell,
1330
1398
  check=check,
@@ -1409,7 +1477,7 @@ class PathBase(PathLike):
1409
1477
  """The stored path string."""
1410
1478
  return self._path
1411
1479
 
1412
- def __eq__(self, other: PathBase) -> bool:
1480
+ def __eq__(self, other: object) -> bool:
1413
1481
  if not isinstance(other, PathBase):
1414
1482
  return NotImplemented
1415
1483
 
@@ -1729,6 +1797,8 @@ class PathBase(PathLike):
1729
1797
  if not self.is_absolute:
1730
1798
  raise ValueError("relative path can't be expressed as a file URI")
1731
1799
 
1800
+ from urllib.request import pathname2url
1801
+
1732
1802
  return "file://" + pathname2url(os.path.abspath(self.path))
1733
1803
 
1734
1804
  def match(self, pattern: str) -> bool:
@@ -1801,40 +1871,6 @@ class PathBase(PathLike):
1801
1871
  def clear(self) -> Self:
1802
1872
  raise NotImplementedError
1803
1873
 
1804
- def move_to(self, target: PathBase, *, mkdir: bool = False, overwrite: bool = True) -> Self:
1805
- """
1806
- Move the path to a new target.
1807
-
1808
- Args:
1809
- target: The destination path object.
1810
- mkdir: Whether to create missing parent directories. Defaults to False.
1811
- overwrite: Whether to overwrite files if they already exist. Defaults to True.
1812
-
1813
- Returns:
1814
- A new path object pointing at the moved path.
1815
- """
1816
- raise NotImplementedError
1817
-
1818
- def copy_to(
1819
- self,
1820
- target: PathBase,
1821
- *,
1822
- mkdir: bool = False,
1823
- overwrite: bool = True,
1824
- ) -> Self:
1825
- """
1826
- Copy the path to a new target.
1827
-
1828
- Args:
1829
- target: The destination path object.
1830
- mkdir: Whether to create missing parent directories. Defaults to False.
1831
- overwrite: Whether to overwrite files if they already exist. Defaults to True.
1832
-
1833
- Returns:
1834
- A new path object pointing at the copied path.
1835
- """
1836
- raise NotImplementedError
1837
-
1838
1874
  if sys.platform != "win32":
1839
1875
 
1840
1876
  def get_xattr(self, name: str, group: str = "user") -> str:
@@ -2040,7 +2076,10 @@ class File(PathBase):
2040
2076
 
2041
2077
  async def read_async(self, mode: Literal["r", "rb"] = "r") -> str | bytes:
2042
2078
  """Async version of read()."""
2043
- return await run_fs_sync(self.read, mode)
2079
+ if mode == "rb":
2080
+ return await run_fs_sync(lambda: self.read("rb"))
2081
+
2082
+ return await run_fs_sync(lambda: self.read("r"))
2044
2083
 
2045
2084
  @overload
2046
2085
  def write(
@@ -2180,18 +2219,22 @@ class File(PathBase):
2180
2219
 
2181
2220
  @overload
2182
2221
  def open(
2183
- self, mode: Literal["r"] = "r", encoding: str | None = None, **kwargs: OpenKwarg
2222
+ self, mode: Literal["r"] = "r", encoding: str | None = None, **kwargs: Unpack[OpenOptions]
2184
2223
  ) -> IO[str]: ...
2185
2224
 
2186
2225
  @overload
2187
2226
  def open(
2188
- self, mode: Literal["rb"], encoding: None = None, **kwargs: OpenKwarg
2227
+ self, mode: Literal["rb"], encoding: None = None, **kwargs: Unpack[OpenOptions]
2189
2228
  ) -> IO[bytes]: ...
2190
2229
 
2191
2230
  @overload
2192
- def open(self, mode: str, encoding: str | None = None, **kwargs: OpenKwarg) -> IO[Any]: ...
2231
+ def open(
2232
+ self, mode: str, encoding: str | None = None, **kwargs: Unpack[OpenOptions]
2233
+ ) -> IO[Any]: ...
2193
2234
 
2194
- def open(self, mode: str = "r", encoding: str | None = None, **kwargs: OpenKwarg) -> IO[Any]:
2235
+ def open(
2236
+ self, mode: str = "r", encoding: str | None = None, **kwargs: Unpack[OpenOptions]
2237
+ ) -> IO[Any]:
2195
2238
  """
2196
2239
  Open the file and return a file handle.
2197
2240
 
@@ -2213,21 +2256,21 @@ class File(PathBase):
2213
2256
 
2214
2257
  @overload
2215
2258
  async def open_async(
2216
- self, mode: Literal["r"] = "r", encoding: str | None = None, **kwargs: OpenKwarg
2259
+ self, mode: Literal["r"] = "r", encoding: str | None = None, **kwargs: Unpack[OpenOptions]
2217
2260
  ) -> AsyncFileHandle[str]: ...
2218
2261
 
2219
2262
  @overload
2220
2263
  async def open_async(
2221
- self, mode: Literal["rb"], encoding: None = None, **kwargs: OpenKwarg
2264
+ self, mode: Literal["rb"], encoding: None = None, **kwargs: Unpack[OpenOptions]
2222
2265
  ) -> AsyncFileHandle[bytes]: ...
2223
2266
 
2224
2267
  @overload
2225
2268
  async def open_async(
2226
- self, mode: str, encoding: str | None = None, **kwargs: OpenKwarg
2269
+ self, mode: str, encoding: str | None = None, **kwargs: Unpack[OpenOptions]
2227
2270
  ) -> AsyncFileHandle[str] | AsyncFileHandle[bytes]: ...
2228
2271
 
2229
2272
  async def open_async(
2230
- self, mode: str = "r", encoding: str | None = None, **kwargs: OpenKwarg
2273
+ self, mode: str = "r", encoding: str | None = None, **kwargs: Unpack[OpenOptions]
2231
2274
  ) -> AsyncFileHandle[str] | AsyncFileHandle[bytes]:
2232
2275
  """Async version of open()."""
2233
2276
  if "b" not in mode and encoding is None:
@@ -2992,7 +3035,7 @@ def _walk_directory(
2992
3035
  *,
2993
3036
  follow_symlinks: bool,
2994
3037
  abs: bool, # noqa: A002
2995
- visited: set[tuple[int, int]] | None,
3038
+ visited: set[DirectoryIdentity] | None,
2996
3039
  ) -> Generator[tuple[Directory, list[Directory], list[File]], None, None]:
2997
3040
  if follow_symlinks:
2998
3041
  if visited is None:
@@ -1,14 +1,8 @@
1
1
  import importlib
2
2
  import sys
3
- from collections.abc import Callable
4
- from typing import Generic, ParamSpec, TypeVar
5
3
 
6
- LazyValueT = TypeVar("LazyValueT")
7
- LazyCallResultT = TypeVar("LazyCallResultT")
8
- P = ParamSpec("P")
9
4
 
10
-
11
- class LazyImport(Generic[LazyValueT]):
5
+ class LazyImport:
12
6
  """A lazy import that loads the actual object on first access."""
13
7
 
14
8
  def __init__(
@@ -20,10 +14,10 @@ class LazyImport(Generic[LazyValueT]):
20
14
  self.module_name = module_name
21
15
  self.attr_name = attr_name
22
16
  self.verbose = verbose
23
- self._cached_value: LazyValueT | None = None
17
+ self._cached_value: object = None
24
18
  self._loaded = False
25
19
 
26
- def _load(self) -> LazyValueT:
20
+ def _load(self) -> object:
27
21
  if not self._loaded:
28
22
  start_time = 0.0
29
23
  if self.verbose:
@@ -70,19 +64,17 @@ class LazyImport(Generic[LazyValueT]):
70
64
 
71
65
  return self._cached_value
72
66
 
73
- def __call__(self, *args: P.args, **kwargs: P.kwargs) -> LazyCallResultT:
67
+ def __call__(self, *args: object, **kwargs: object) -> object:
74
68
  loaded = self._load()
75
69
  if not callable(loaded):
76
70
  raise TypeError(f"{loaded!r} is not callable")
77
71
 
78
- loaded_callable: Callable[P, LazyCallResultT] = loaded
79
-
80
- return loaded_callable(*args, **kwargs)
72
+ return loaded(*args, **kwargs)
81
73
 
82
- def __getattr__(self, name: str) -> LazyValueT:
74
+ def __getattr__(self, name: str) -> object:
83
75
  return getattr(self._load(), name)
84
76
 
85
- def __setattr__(self, name: str, value: LazyValueT) -> None:
77
+ def __setattr__(self, name: str, value: object) -> None:
86
78
  if name in ("module_name", "attr_name", "verbose", "_cached_value", "_loaded"):
87
79
  super().__setattr__(name, value)
88
80
  else:
@@ -95,37 +95,38 @@ def get_logging_config(
95
95
  or "{asctime} | {levelname:<8s} | [ {name} ] {module}.{funcName}:{lineno} - {message}"
96
96
  )
97
97
 
98
- config = {
99
- "version": 1,
100
- "disable_existing_loggers": disable_existing,
101
- "formatters": {
102
- "standard": {
103
- "format": resolved_format,
104
- "datefmt": "%Y-%m-%d %H:%M:%S",
105
- "style": format_style,
106
- }
107
- },
108
- "handlers": {
109
- "console": {
110
- "class": console_handler,
111
- "level": level,
112
- "formatter": "standard",
113
- "stream": "ext://sys.stdout",
114
- },
98
+ handlers: dict[str, dict[str, str | int]] = {
99
+ "console": {
100
+ "class": console_handler,
101
+ "level": level,
102
+ "formatter": "standard",
103
+ "stream": "ext://sys.stdout",
115
104
  },
116
- "root": {"level": level, "handlers": ["console"]},
117
105
  }
106
+ root_handlers = ["console"]
118
107
  if filename:
119
- config["handlers"]["file"] = {
108
+ handlers["file"] = {
120
109
  "class": file_handler,
121
110
  "level": level,
122
111
  "formatter": "standard",
123
112
  "backupCount": backup_count,
124
113
  "filename": filename,
125
114
  }
126
- config["root"]["handlers"].append("file")
115
+ root_handlers.append("file")
127
116
 
128
- return config
117
+ return {
118
+ "version": 1,
119
+ "disable_existing_loggers": disable_existing,
120
+ "formatters": {
121
+ "standard": {
122
+ "format": resolved_format,
123
+ "datefmt": "%Y-%m-%d %H:%M:%S",
124
+ "style": format_style,
125
+ }
126
+ },
127
+ "handlers": handlers,
128
+ "root": {"level": level, "handlers": root_handlers},
129
+ }
129
130
 
130
131
 
131
132
  def br(
@@ -1,13 +1,12 @@
1
1
  import os
2
2
  import re
3
+ import sys
3
4
  import textwrap
5
+ import unicodedata
4
6
  from dataclasses import dataclass
5
- from platform import system
6
- from sys import stdout
7
- from typing import Literal, TypeAlias
7
+ from typing import Literal, TextIO, TypeAlias
8
8
 
9
9
  CSI_RESET = "\033["
10
- NO_COLOR = bool(os.environ.get("NO_COLOR"))
11
10
  ANSI_ESCAPE_RE = re.compile(r"\x1B(?:\][^\x1B\x07]*(?:\x07|\x1B\\)|\[[0-?]*[ -/]*[@-~]|[@-Z\\-_])")
12
11
 
13
12
 
@@ -15,43 +14,25 @@ def ansi_code(n: int) -> str:
15
14
  return f"{CSI_RESET}{n}m"
16
15
 
17
16
 
18
- class ColorANSI:
19
- # Enable VT mode on Windows
20
- if stdout.isatty() and system() == "Windows":
21
- import ctypes
22
-
23
- kernel32 = ctypes.windll.kernel32
24
- handle = kernel32.GetStdHandle(-11)
25
- if handle:
26
- kernel32.SetConsoleMode(handle, 7)
27
-
28
- del kernel32
29
- del handle
30
- del ctypes
31
-
32
- @classmethod
33
- def __class_getitem__(cls, key: str) -> str:
17
+ class ColorANSIMeta(type):
18
+ def __getitem__(cls, key: str) -> str:
34
19
  key = key.upper().replace(" ", "_")
35
20
  if key in dir(cls):
36
21
  return getattr(cls, key)
37
22
 
38
23
  raise KeyError(key)
39
24
 
40
- @classmethod
41
25
  def dict(cls) -> dict[str, str]:
42
- ignored = ["dict", "print_all", "get_names"]
43
26
  data = {}
44
27
  for attr in dir(cls):
45
- if attr[0] != "_" and attr not in ignored:
28
+ if attr[0] != "_":
46
29
  data[attr] = cls[attr]
47
30
 
48
31
  return data
49
32
 
50
- @classmethod
51
33
  def get_names(cls) -> list[str]:
52
34
  return list(cls.dict())
53
35
 
54
- @classmethod
55
36
  def print_all(cls) -> None:
56
37
  for k, v in cls.dict().items():
57
38
  if k == "RESET":
@@ -60,6 +41,21 @@ class ColorANSI:
60
41
  print(colored(k, color=v))
61
42
 
62
43
 
44
+ class ColorANSI(metaclass=ColorANSIMeta):
45
+ # Enable VT mode on Windows
46
+ if sys.platform == "win32" and sys.stdout.isatty():
47
+ import ctypes
48
+
49
+ kernel32 = ctypes.windll.kernel32
50
+ handle = kernel32.GetStdHandle(-11)
51
+ if handle:
52
+ kernel32.SetConsoleMode(handle, 7)
53
+
54
+ del kernel32
55
+ del handle
56
+ del ctypes
57
+
58
+
63
59
  class FG(ColorANSI):
64
60
  """Foreground color."""
65
61
 
@@ -157,7 +153,7 @@ BackgroundColor: TypeAlias = Literal[
157
153
  Style: TypeAlias = Literal["blink", "bold", "dim", "italic", "reset", "underline"]
158
154
 
159
155
 
160
- def _get_ansi_value(value: str | None, handler: type[ColorANSI]) -> str:
156
+ def _get_ansi_value(value: str | None, handler: ColorANSIMeta) -> str:
161
157
  if not value:
162
158
  return ""
163
159
 
@@ -167,25 +163,48 @@ def _get_ansi_value(value: str | None, handler: type[ColorANSI]) -> str:
167
163
  return value
168
164
 
169
165
 
166
+ def color_enabled(stream: TextIO | None = None) -> bool:
167
+ """
168
+ Return whether ANSI escape codes should be written to ``stream``.
169
+
170
+ Codes are off when ``NO_COLOR`` or ``NOCOLOR`` is set to any value, when ``TERM`` is
171
+ ``dumb``, or when the stream is not a terminal. The environment is read on every call.
172
+
173
+ Args:
174
+ stream (TextIO, optional): The stream the text is written to. Defaults to the current
175
+ ``sys.stdout``.
176
+ """
177
+ if "NO_COLOR" in os.environ or "NOCOLOR" in os.environ or os.environ.get("TERM") == "dumb":
178
+ return False
179
+
180
+ return (sys.stdout if stream is None else stream).isatty()
181
+
182
+
170
183
  def colored(
171
184
  text: str,
172
185
  color: ForegroundColor | str | None = None,
173
186
  background: BackgroundColor | str | None = None,
174
187
  style: Style | str | None = None,
188
+ *,
189
+ stream: TextIO | None = None,
175
190
  ) -> str:
176
191
  """
177
192
  Returns the text with ansi color, background color and text style codes.
178
193
 
194
+ Returns the text unchanged when ``color_enabled(stream)`` is false.
195
+
179
196
  Args:
180
197
  text (str): The text that should be colorized.
181
198
  color (str, optional): The color to use for the text.
182
199
  background (str, optional): The color to use for the background.
183
200
  style (str, optional): The style to use for the text.
201
+ stream (TextIO, optional): The stream the text is written to. Defaults to the current
202
+ ``sys.stdout``.
184
203
 
185
204
  Returns:
186
205
  str: The colorized text.
187
206
  """
188
- if NO_COLOR or not stdout.isatty():
207
+ if not color_enabled(stream):
189
208
  return text
190
209
 
191
210
  color = _get_ansi_value(color, FG)
@@ -202,8 +221,10 @@ class TextStyle:
202
221
  style: Style | str | None = None
203
222
 
204
223
 
205
- def with_style(text: str, style: TextStyle) -> str:
206
- return colored(text, color=style.color, background=style.background, style=style.style)
224
+ def with_style(text: str, style: TextStyle, *, stream: TextIO | None = None) -> str:
225
+ return colored(
226
+ text, color=style.color, background=style.background, style=style.style, stream=stream
227
+ )
207
228
 
208
229
 
209
230
  def terminal_link(
@@ -212,6 +233,8 @@ def terminal_link(
212
233
  color: ForegroundColor | None = "white",
213
234
  background: BackgroundColor | None = None,
214
235
  style: Style | None = None,
236
+ *,
237
+ stream: TextIO | None = None,
215
238
  ) -> str:
216
239
  """
217
240
  Returns a hyperlink that can be used in terminals.
@@ -229,6 +252,9 @@ def terminal_link(
229
252
  color (str, optional): The color of the link. Defaults to white.
230
253
  background (str, optional): The background color of the link.
231
254
  style (str, optional): The style of the link.
255
+ stream (TextIO, optional): The stream the link is written to. Without terminal escape
256
+ support (see ``color_enabled``), the plain URI is returned. Defaults to the current
257
+ ``sys.stdout``.
232
258
 
233
259
  Returns:
234
260
  str: The link as a string.
@@ -236,8 +262,11 @@ def terminal_link(
236
262
  if label is None:
237
263
  label = uri
238
264
 
239
- link = f"\033]8;;{uri}\033\\{label}\033]8;;\033\\" if stdout.isatty() else uri
240
- link = colored(link, color, background, style)
265
+ if not color_enabled(stream):
266
+ return uri
267
+
268
+ link = f"\033]8;;{uri}\033\\{label}\033]8;;\033\\"
269
+ link = colored(link, color, background, style, stream=stream)
241
270
 
242
271
  return link
243
272
 
@@ -333,22 +362,33 @@ def camel_case(s: str) -> str:
333
362
  return s[0].lower() + s[1:]
334
363
 
335
364
 
365
+ def _char_class(c: str) -> str:
366
+ if c.isupper():
367
+ return "A"
368
+ if c.isalpha():
369
+ return "a"
370
+ if c.isdigit():
371
+ return "0"
372
+
373
+ return c
374
+
375
+
336
376
  def kebab_case(s: str) -> str:
337
377
  """Converts a given string to kebab-case."""
338
378
  RE_WORDS = r"[A-Z]{2,}(?=[A-Z][a-z]+[0-9]*|\b)|[A-Z]?[a-z]+[0-9]*|[A-Z]|[0-9]+"
339
379
  RE_SEP = r"(\s|_|-)+"
340
380
 
341
- return "-".join(
342
- re.sub(
343
- RE_SEP,
344
- " ",
345
- re.sub(
346
- RE_WORDS,
347
- lambda mo: " " + mo.group(0).lower(),
348
- s,
349
- ),
350
- ).split()
351
- )
381
+ # `re` has no Unicode case classes, so words are matched on a same-length ASCII stand-in.
382
+ classes = "".join(_char_class(c) for c in s)
383
+ spaced: list[str] = []
384
+ end = 0
385
+ for mo in re.finditer(RE_WORDS, classes):
386
+ spaced.extend((s[end : mo.start()], " ", s[mo.start() : mo.end()].lower()))
387
+ end = mo.end()
388
+
389
+ spaced.append(s[end:])
390
+
391
+ return "-".join(re.sub(RE_SEP, " ", "".join(spaced)).split())
352
392
 
353
393
 
354
394
  def wrapped(text: str, width: int, newline: str = "\n") -> str:
@@ -356,9 +396,18 @@ def wrapped(text: str, width: int, newline: str = "\n") -> str:
356
396
  return newline.join(textwrap.wrap(text, width=width))
357
397
 
358
398
 
399
+ def _char_width(c: str) -> int:
400
+ if unicodedata.combining(c):
401
+ return 0
402
+ if unicodedata.east_asian_width(c) in {"W", "F"}:
403
+ return 2
404
+
405
+ return 1
406
+
407
+
359
408
  def ansi_len(s: str) -> int:
360
- """Returns the length of the string without the ANSI codes."""
361
- return len(ansi_strip(s))
409
+ """Returns the terminal display width of the string without the ANSI codes."""
410
+ return sum(_char_width(c) for c in ansi_strip(s))
362
411
 
363
412
 
364
413
  def ansi_ljust(s: str, width: int, fillchar: str = " ") -> str:
@@ -408,6 +457,7 @@ __all__ = [
408
457
  "ansi_ljust",
409
458
  "ansi_rjust",
410
459
  "camel_case",
460
+ "color_enabled",
411
461
  "colored",
412
462
  "kebab_case",
413
463
  "keep",
stdl-0.8.0/README.md DELETED
@@ -1,49 +0,0 @@
1
- # stdl
2
-
3
- [![Tests](https://github.com/zigai/stdl/actions/workflows/test.yml/badge.svg)](https://github.com/zigai/stdl/actions/workflows/test.yml)
4
- [![Documentation Status](https://readthedocs.org/projects/stdl/badge/?version=latest)](https://stdl.readthedocs.io/en/latest/?badge=latest)
5
- [![PyPI version](https://badge.fury.io/py/stdl.svg)](https://badge.fury.io/py/stdl)
6
- ![Supported versions](https://img.shields.io/badge/python-3.11+-blue.svg)
7
- [![Downloads](https://static.pepy.tech/badge/stdl)](https://pepy.tech/project/stdl)
8
- [![license](https://img.shields.io/github/license/zigai/stdl.svg)](https://github.com/zigai/stdl/blob/master/LICENSE)
9
-
10
- `stdl` is a collection of Python utilities that complement the standard library.
11
-
12
- ## Features
13
-
14
- - File and directory operations
15
- - String manipulation
16
- - ANSI color support for terminal output
17
- - Date and time formatting
18
- - List utils
19
- - Lazy imports
20
- - Logging configuration for `logging` and `loguru`
21
- - [See docs](https://stdl.readthedocs.io/en/latest/?badge=latest)
22
-
23
- ## Installation
24
-
25
- ### Using pip
26
-
27
- ```sh
28
- pip install stdl
29
- pip install 'stdl[async]'
30
- ```
31
-
32
- ### Using uv
33
-
34
- ```sh
35
- uv add stdl
36
- uv add 'stdl[async]'
37
- ```
38
-
39
- ### From source
40
-
41
- ```sh
42
- pip install git+https://github.com/zigai/stdl.git
43
- # or
44
- uv add git+https://github.com/zigai/stdl.git
45
- ```
46
-
47
- ## License
48
-
49
- [MIT License](https://github.com/zigai/stdl/blob/master/LICENSE)
File without changes
File without changes
File without changes
File without changes
File without changes