Coverage for src/homeassistant_repl/complete.py: 85%
616 statements
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-17 19:05 +0000
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-17 19:05 +0000
1"""Completion that runs nothing: the attribute chain or key at the cursor is
2followed with inspect.getattr_static and type annotations, never by
3evaluating it - no property, __getattr__, __getitem__ or call of anything
4but a plain dict, list or tuple, or one of this project's own classes marked
5`_ha_repl_inspectable` (the object trees and registry entries, whose
6lookups only look things up). See RFC 0002.
8Kept identical in homeassistant_repl/complete.py (the shell's local
9completion) and custom_components/ha_repl_server/complete.py (the server's
10`ha_repl_server/complete`); tests/test_complete.py checks they match.
11Standard library only, and no Home Assistant imports, for the same reason.
12"""
14from __future__ import annotations
16import annotationlib
17import ast
18import builtins
19import inspect
20import keyword
21import re
22import reprlib
23import sys
24import time
25import types
26from collections.abc import Iterable, Iterator, Mapping
27from dataclasses import dataclass, field
28from typing import Any
30# At most this many items in one answer, and this many seconds spent
31# finding them; more of either makes it `incomplete`.
32LIMIT = 500
33BUDGET = 0.5
35# The methods whose first argument is a path in the tree they're called on.
36_PATH_METHODS = frozenset({"find", "find_paths", "find_names"})
38_IDENTIFIER_END = re.compile(r"\w*$")
39_IMPORTING = re.compile(r"(^|[\s;])(import|from)\s[\w.,\s]*$")
40_MISSING = object()
43@dataclass
44class Item:
45 label: str
46 kind: str
47 detail: str = ""
50@dataclass
51class Completions:
52 """What can go at the cursor: each item's label replaces the `replace`
53 characters before it. `incomplete` if more matched than were sent."""
55 items: list[Item] = field(default_factory=list)
56 replace: int = 0
57 incomplete: bool = False
59 def as_dict(self) -> dict[str, Any]:
60 return {
61 "items": [
62 {"label": i.label, "kind": i.kind, "detail": i.detail}
63 for i in self.items
64 ],
65 "replace": self.replace,
66 "incomplete": self.incomplete,
67 }
70@dataclass
71class Param:
72 name: str
73 text: str # as written: `path: str = '/'`, `*args`
74 kind: str # inspect.Parameter's kind, by name
77@dataclass
78class Signature:
79 """The signature of the call the cursor is in."""
81 name: str
82 params: list[Param]
83 returns: str = ""
84 doc: str = "" # the docstring's first line
86 def as_dict(self) -> dict[str, Any]:
87 return {
88 "name": self.name,
89 "params": [vars(p) for p in self.params],
90 "returns": self.returns,
91 "doc": self.doc,
92 }
94 @classmethod
95 def from_dict(cls, data: dict[str, Any]) -> Signature:
96 fields: dict[str, Any] = {
97 **data,
98 "params": [Param(**p) for p in data["params"]],
99 }
100 return cls(**fields)
102 def active(self, position: int, keyword: str | None) -> int | None:
103 """Which parameter an argument at `position`, or given as
104 `keyword`, goes to."""
105 kinds = [p.kind for p in self.params]
106 if keyword is not None:
107 for i, param in enumerate(self.params): 107 ↛ 110line 107 didn't jump to line 110 because the loop on line 107 didn't complete
108 if param.name == keyword and param.kind != "POSITIONAL_ONLY":
109 return i
110 return kinds.index("VAR_KEYWORD") if "VAR_KEYWORD" in kinds else None
111 positional = [
112 i
113 for i, kind in enumerate(kinds)
114 if kind in ("POSITIONAL_ONLY", "POSITIONAL_OR_KEYWORD")
115 ]
116 if position < len(positional):
117 return positional[position]
118 return kinds.index("VAR_POSITIONAL") if "VAR_POSITIONAL" in kinds else None
121@dataclass(frozen=True)
122class _Value:
123 """A real object, found without running anything - with the class it
124 was found on, for a method's `Self`."""
126 obj: Any
127 owner: type | None = None
130@dataclass(frozen=True)
131class _Type:
132 """Only the type is known, from an annotation."""
134 cls: type
137class _Absent:
138 """Looked for in a way that can't run anything, and not there: nothing
139 to complete, as opposed to not knowing."""
142_ABSENT = _Absent()
144_Found = _Value | _Type | _Absent
147def context_start(text: str) -> int:
148 """Where the word or string being typed at the end of `text` starts:
149 what's before it decides what can complete it, and stays the same as
150 more of it is typed."""
151 if (string := _open_string(text)) is not None:
152 return string + 1
153 return _IDENTIFIER_END.search(text).start() # type: ignore[union-attr] # ty: ignore[missing-union-attribute]
156def kind_at(text: str) -> str:
157 """What's being typed at the end of `text`: "string", "attribute" (after
158 a `.`) or "name"."""
159 if _open_string(text) is not None:
160 return "string"
161 return "attribute" if text[: context_start(text)].endswith(".") else "name"
164def complete(
165 source: str,
166 cursor: int,
167 namespace: Mapping[str, Any],
168 *,
169 limit: int = LIMIT,
170 budget: float | None = BUDGET,
171) -> Completions | None:
172 """The completions at `cursor` in `source`, against `namespace`. None
173 when the expression before the cursor can't be followed without running
174 something, for a caller with another way to try."""
175 clock = _Budget(budget)
176 found = _complete(source[:cursor], namespace, limit, clock)
177 if found is not None:
178 found.incomplete |= clock.ran_out
179 return found
182class _Budget:
183 """Stops going through something big once the time's up."""
185 def __init__(self, seconds: float | None) -> None:
186 self.deadline = None if seconds is None else time.monotonic() + seconds
187 self.ran_out = False
189 def take[T](self, items: Iterable[T]) -> Iterator[T]:
190 for n, item in enumerate(items):
191 if (
192 self.deadline is not None
193 and n % 64 == 0
194 and time.monotonic() > self.deadline
195 ):
196 self.ran_out = True
197 return
198 yield item
201def _complete(
202 text: str, namespace: Mapping[str, Any], limit: int, clock: _Budget
203) -> Completions | None:
204 if (quote := _open_string(text)) is not None:
205 return _complete_string(text, quote, namespace, limit, clock)
206 prefix = _IDENTIFIER_END.search(text).group() # type: ignore[union-attr] # ty: ignore[missing-union-attribute]
207 before = text[: len(text) - len(prefix)]
208 if before.endswith("."):
209 if (expr := _expression_before(before[:-1])) is None: 209 ↛ 210line 209 didn't jump to line 210 because the condition on line 209 was never true
210 return None
211 found = _resolve(expr, namespace)
212 if found is None:
213 return None
214 if isinstance(found, _Absent):
215 return Completions()
216 return _matching(_members(found), prefix, limit, clock)
217 if _IMPORTING.search(before.rsplit("\n", 1)[-1]):
218 return None
219 names = _keywords(text, namespace) | _names(namespace)
220 return _matching(names, prefix, limit, clock)
223def call_at(text: str) -> tuple[int, int, str | None] | None:
224 """The innermost call the end of `text` is inside: where its `(` is,
225 which argument is being typed (counting from 0), and the keyword it's
226 being given as, if any. None outside a call's brackets."""
227 stack: list[list[Any]] = [] # bracket, where, commas, last comma
228 quote = ""
229 i = 0
230 while i < len(text):
231 ch = text[i]
232 if quote:
233 if ch == "\\": 233 ↛ 234line 233 didn't jump to line 234 because the condition on line 233 was never true
234 i += 1
235 elif text.startswith(quote, i):
236 i += len(quote) - 1
237 quote = ""
238 elif ch == "#": 238 ↛ 239line 238 didn't jump to line 239 because the condition on line 238 was never true
239 while i < len(text) and text[i] != "\n":
240 i += 1
241 elif ch in "'\"":
242 quote = ch * 3 if text.startswith(ch * 3, i) else ch
243 i += len(quote) - 1
244 elif ch in "([{":
245 stack.append([ch, i, 0, i])
246 elif ch in ")]}" and stack:
247 stack.pop()
248 elif ch == "," and stack:
249 stack[-1][2] += 1
250 stack[-1][3] = i
251 i += 1
252 if not stack or stack[-1][0] != "(":
253 return None
254 _, paren, commas, last = stack[-1]
255 named = re.match(r"\s*(\w+)\s*=(?!=)", text[last + 1 :])
256 return paren, commas, named.group(1) if named else None
259def signature(
260 source: str, cursor: int, namespace: Mapping[str, Any]
261) -> Signature | None:
262 """The signature of the call `cursor` is inside, if it can be found
263 without running anything."""
264 text = source[:cursor]
265 if (call := call_at(text)) is None:
266 return None
267 if (callee := _expression_before(text[: call[0]])) is None:
268 return None
269 found = _resolve(callee, namespace)
270 if not isinstance(found, _Value):
271 return None
272 obj = found.obj
273 func = obj
274 if isinstance(obj, type):
275 func = inspect.getattr_static(obj, "__init__", None)
276 if func is None or func is object.__init__: 276 ↛ 277line 276 didn't jump to line 277 because the condition on line 276 was never true
277 return None
278 if (inspected := _inspect_signature(func)) is None: 278 ↛ 279line 278 didn't jump to line 279 because the condition on line 278 was never true
279 return None
280 # As called: the name a function has for itself is a descriptor away.
281 name = ast.unparse(callee).rsplit(".", 1)[-1].split("(", 1)[0]
282 doc = _doc(obj)
283 returns = inspected.return_annotation
284 return Signature(
285 name,
286 [_param(p) for p in inspected.parameters.values()],
287 "" if returns is inspect.Signature.empty else str(returns),
288 next((line.strip() for line in doc.splitlines() if line.strip()), "")[:120]
289 if isinstance(doc, str)
290 else "",
291 )
294def _doc(obj: Any) -> str | None:
295 """A docstring, read only where reading it can't run anything."""
296 if isinstance(obj, type):
297 doc = vars(obj).get("__doc__")
298 elif isinstance( 298 ↛ 303line 298 didn't jump to line 303 because the condition on line 298 was always true
299 obj, (types.FunctionType, types.BuiltinFunctionType, types.MethodType)
300 ):
301 doc = obj.__doc__
302 else:
303 doc = inspect.getattr_static(obj, "__doc__", None)
304 return doc if isinstance(doc, str) else None
307def _param(param: inspect.Parameter) -> Param:
308 text = param.name
309 if param.kind is param.VAR_POSITIONAL: 309 ↛ 310line 309 didn't jump to line 310 because the condition on line 309 was never true
310 text = "*" + text
311 elif param.kind is param.VAR_KEYWORD: 311 ↛ 312line 311 didn't jump to line 312 because the condition on line 311 was never true
312 text = "**" + text
313 if param.annotation is not param.empty:
314 text += f": {param.annotation}"
315 if param.default is not param.empty:
316 default = param.default
317 # Only a value whose repr can't run anything is shown as itself.
318 plain = default is None or type(default) in (str, int, float, bool, bytes)
319 text += f" = {default!r}" if plain else f" = <{type(default).__name__}>"
320 return Param(param.name, text, param.kind.name)
323def _keywords(text: str, namespace: Mapping[str, Any]) -> dict[str, Item]:
324 """Inside a call, its parameters not given yet, as `name=`."""
325 if (call := call_at(text)) is None or call[2] is not None:
326 return {}
327 found = signature(text, len(text), namespace)
328 if found is None: 328 ↛ 329line 328 didn't jump to line 329 because the condition on line 328 was never true
329 return {}
330 given = set(re.findall(r"(\w+)\s*=(?!=)", text[call[0] + 1 :]))
331 return {
332 f"{param.name}=": Item(f"{param.name}=", "parameter", param.text)
333 for param in found.params
334 if param.kind in ("POSITIONAL_OR_KEYWORD", "KEYWORD_ONLY")
335 and param.name not in given
336 }
339def _complete_string(
340 text: str, quote: int, namespace: Mapping[str, Any], limit: int, clock: _Budget
341) -> Completions:
342 """Keys inside `x["`, and paths inside `obj.find("`. Nothing anywhere
343 else in a string - not file names, say."""
344 partial = text[quote + 1 :]
345 before = text[:quote].rstrip()
346 while before and before[-1] in "rRbBuU": 346 ↛ 347line 346 didn't jump to line 347 because the condition on line 346 was never true
347 before = before[:-1]
348 keys: Iterable[str] = ()
349 if before.endswith("["):
350 if (expr := _expression_before(before[:-1])) is not None: 350 ↛ 360line 350 didn't jump to line 360 because the condition on line 350 was always true
351 target = _resolve(expr, namespace)
352 if isinstance(target, _Value): 352 ↛ 360line 352 didn't jump to line 360 because the condition on line 352 was always true
353 keys = _keys(target.obj)
354 elif before.endswith("("): 354 ↛ 360line 354 didn't jump to line 360 because the condition on line 354 was always true
355 call = _expression_before(before[:-1])
356 if isinstance(call, ast.Attribute) and call.attr in _PATH_METHODS:
357 target = _resolve(call.value, namespace)
358 if isinstance(target, _Value) and _inspectable(target.obj): 358 ↛ 360line 358 didn't jump to line 360 because the condition on line 358 was always true
359 keys = (k for k in _keys(target.obj) if k.startswith("/"))
360 items = [Item(k, "key") for k in clock.take(keys) if partial.lower() in k.lower()]
361 items.sort(key=lambda i: rank(i.label, partial))
362 result = Completions(items[:limit], len(partial))
363 result.incomplete = len(items) > limit
364 return result
367def _open_string(text: str) -> int | None:
368 """Where the string literal open at the end of `text` starts, if one is."""
369 line_start = text.rfind("\n") + 1
370 quote: str | None = None
371 start = 0
372 i = line_start
373 while i < len(text):
374 ch = text[i]
375 if quote is not None:
376 if ch == "\\": 376 ↛ 377line 376 didn't jump to line 377 because the condition on line 376 was never true
377 i += 1
378 elif ch == quote:
379 quote = None
380 elif ch in "'\"":
381 if text.startswith(ch * 3, i): 381 ↛ 382line 381 didn't jump to line 382 because the condition on line 381 was never true
382 return None # triple quoted: not a key
383 quote, start = ch, i
384 elif ch == "#": 384 ↛ 385line 384 didn't jump to line 385 because the condition on line 384 was never true
385 return None
386 i += 1
387 return start if quote is not None else None
390def expression_at(text: str, after: str = "") -> str:
391 """The name or attribute chain the cursor is on - `text` is before it,
392 `after` after it - or, between a call's brackets, the callee. "" if
393 neither."""
394 word = re.match(r"\w*", after).group() # type: ignore[union-attr] # ty: ignore[missing-union-attribute]
395 full = text + word
396 if (found := _expression_start(full)) is not None and full[found:].strip():
397 return full[found:]
398 if (call := call_at(text)) is not None:
399 callee = text[: call[0]]
400 if (found := _expression_start(callee)) is not None: 400 ↛ 402line 400 didn't jump to line 402 because the condition on line 400 was always true
401 return callee[found:]
402 return ""
405def _expression_start(text: str) -> int | None:
406 i = _scan_back(text)
407 return i if i is not None and _parse(text[i:]) is not None else None
410def _expression_before(text: str) -> ast.expr | None:
411 """The name, attribute, call or subscript chain that `text` ends with."""
412 i = _scan_back(text)
413 return None if i is None else _parse(text[i:])
416def _scan_back(text: str) -> int | None:
417 i = len(text)
418 depth = 0
419 while i > 0:
420 ch = text[i - 1]
421 if ch in ")]":
422 depth += 1
423 elif ch in "([":
424 if depth == 0: 424 ↛ 425line 424 didn't jump to line 425 because the condition on line 424 was never true
425 break
426 depth -= 1
427 elif depth == 0 and ch in "'\"" and (start := text.rfind(ch, 0, i - 1)) >= 0:
428 i = start # a string literal: `"abc".`
429 continue
430 elif depth == 0 and not (ch.isalnum() or ch in "_."):
431 break
432 i -= 1
433 return i if depth == 0 else None
436def _parse(expr: str) -> ast.expr | None:
437 if not expr.strip():
438 return None
439 try:
440 return ast.parse(expr, mode="eval").body
441 except SyntaxError, ValueError:
442 return None
445def _resolve(node: ast.expr, namespace: Mapping[str, Any]) -> _Found | None:
446 match node:
447 case ast.Name(id=name):
448 if name in namespace:
449 return _Value(namespace[name])
450 if (value := getattr(builtins, name, _MISSING)) is not _MISSING:
451 return _Value(value)
452 return None
453 case ast.Constant(value=value):
454 return _Value(value)
455 case ast.Attribute(value=owner, attr=name):
456 found = _resolve(owner, namespace)
457 if found is None or isinstance(found, _Absent):
458 return found
459 return _attribute(found, name)
460 case ast.Subscript(value=owner, slice=key):
461 found = _resolve(owner, namespace)
462 if not isinstance(found, _Value): 462 ↛ 463line 462 didn't jump to line 463 because the condition on line 462 was never true
463 return found if isinstance(found, _Absent) else None
464 try:
465 index = ast.literal_eval(key)
466 except ValueError, SyntaxError, TypeError:
467 return None
468 if not _subscriptable(found.obj):
469 return None
470 try:
471 return _Value(found.obj[index])
472 except Exception: # noqa: BLE001 - a missing key is just nothing to complete
473 return _ABSENT
474 case ast.Call(func=func):
475 found = _resolve(func, namespace)
476 if not isinstance(found, _Value):
477 return found if isinstance(found, _Absent) else None
478 if isinstance(found.obj, type): 478 ↛ 479line 478 didn't jump to line 479 because the condition on line 478 was never true
479 return _Type(found.obj)
480 return _returns(found.obj, found.owner)
481 return None
484def _attribute(found: _Value | _Type, name: str) -> _Found | None:
485 if isinstance(found, _Value): 485 ↛ 495line 485 didn't jump to line 495 because the condition on line 485 was always true
486 obj = found.obj
487 if _inspectable(obj):
488 try:
489 return _Value(getattr(obj, name))
490 except Exception: # noqa: BLE001 - not there is nothing to complete
491 return _ABSENT
492 raw = inspect.getattr_static(obj, name, _MISSING)
493 owner = obj if isinstance(obj, type) else type(obj)
494 else:
495 owner = found.cls
496 raw = inspect.getattr_static(owner, name, _MISSING)
497 if raw is _MISSING:
498 annotation = _declared(owner).get(name)
499 return None if annotation is None else _annotated(annotation, owner)
500 if isinstance(raw, property):
501 return None if raw.fget is None else _returns(raw.fget, owner)
502 if isinstance(raw, (staticmethod, classmethod)): 502 ↛ 503line 502 didn't jump to line 503 because the condition on line 502 was never true
503 return _Value(raw.__func__, owner)
504 if isinstance(raw, types.FunctionType):
505 return _Value(raw, owner)
506 if isinstance(raw, types.MemberDescriptorType) and isinstance(found, _Value): 506 ↛ 507line 506 didn't jump to line 507 because the condition on line 506 was never true
507 try:
508 return _Value(raw.__get__(found.obj)) # a __slots__ value: no code runs
509 except AttributeError:
510 return None
511 if isinstance(found, _Type) and not callable(raw) and name in _declared(owner): 511 ↛ 513line 511 didn't jump to line 513 because the condition on line 511 was never true
512 # A class default, but the annotation says more about the instance's.
513 return _annotated(_declared(owner)[name], owner)
514 return _Value(raw)
517def _subscriptable(obj: Any) -> bool:
518 """Indexing it only looks something up."""
519 if _inspectable(obj):
520 return True
521 for kind in (dict, list, tuple):
522 if isinstance(obj, kind):
523 return inspect.getattr_static(type(obj), "__getitem__") is kind.__getitem__
524 return False
527def _inspectable(obj: Any) -> bool:
528 """One of this project's own classes, whose attributes, keys and dir()
529 only look things up."""
530 return inspect.getattr_static(type(obj), "_ha_repl_inspectable", False) is True
533def _keys(obj: Any) -> Iterable[str]:
534 if _inspectable(obj):
535 method = inspect.getattr_static(type(obj), "_ipython_key_completions_", None)
536 if method is not None: 536 ↛ 538line 536 didn't jump to line 538 because the condition on line 536 was always true
537 return method(obj)
538 if isinstance(obj, dict) and _subscriptable(obj):
539 return (k for k in dict.keys(obj) if isinstance(k, str))
540 return ()
543def _returns(func: Any, owner: type | None = None) -> _Type | None:
544 """The type a call of `func` gives back, going by its annotation."""
545 annotation = _annotations(func).get("return")
546 if annotation is None: 546 ↛ 547line 546 didn't jump to line 547 because the condition on line 546 was never true
547 return None
548 found = _annotated(annotation, owner, getattr(func, "__globals__", None))
549 return found if isinstance(found, _Type) else None
552def _annotations(obj: Any) -> dict[str, str]:
553 """Annotations as written, as strings - without evaluating them."""
554 try:
555 return annotationlib.get_annotations(obj, format=annotationlib.Format.STRING)
556 except Exception: # noqa: BLE001 - no annotations to go by
557 return {}
560def _declared(cls: type) -> dict[str, str]:
561 """The attribute annotations of a class and its bases."""
562 declared: dict[str, str] = {}
563 for klass in reversed(cls.__mro__):
564 declared |= _annotations(klass)
565 return declared
568def _annotated(
569 annotation: str, owner: type | None, globals_: Mapping[str, Any] | None = None
570) -> _Type | None:
571 """The class an annotation names - the first, of a union - looked up by
572 name, never evaluated."""
573 if globals_ is None: 573 ↛ 574line 573 didn't jump to line 574 because the condition on line 573 was never true
574 module = sys.modules.get(owner.__module__) if owner is not None else None
575 globals_ = vars(module) if module is not None else {}
576 node = _parse(annotation)
577 for name in _named(node): 577 ↛ 583line 577 didn't jump to line 583 because the loop on line 577 didn't complete
578 if name in ("Self", "typing.Self") and owner is not None:
579 return _Type(owner)
580 cls = _lookup(name, globals_)
581 if isinstance(cls, type) and cls is not type(None): 581 ↛ 577line 581 didn't jump to line 577 because the condition on line 581 was always true
582 return _Type(cls)
583 return None
586def _named(node: ast.expr | None) -> Iterable[str]:
587 """The class names an annotation could mean, most likely first."""
588 match node:
589 case ast.Constant(value=str(text)): 589 ↛ 590line 589 didn't jump to line 590 because the pattern on line 589 never matched
590 yield from _named(_parse(text))
591 case ast.Name() | ast.Attribute():
592 yield ast.unparse(node)
593 case ast.BinOp(op=ast.BitOr(), left=left, right=right): 593 ↛ 596line 593 didn't jump to line 596 because the pattern on line 593 always matched
594 yield from _named(left)
595 yield from _named(right)
596 case ast.Subscript(value=origin, slice=args):
597 if ast.unparse(origin).rsplit(".", 1)[-1] in ("Optional", "Union"):
598 for arg in args.elts if isinstance(args, ast.Tuple) else [args]:
599 yield from _named(arg)
600 else:
601 yield from _named(origin)
604def _lookup(dotted: str, globals_: Mapping[str, Any]) -> Any:
605 first, *rest = dotted.split(".")
606 value = globals_.get(first, getattr(builtins, first, _MISSING))
607 for part in rest: 607 ↛ 608line 607 didn't jump to line 608 because the loop on line 607 never started
608 if value is _MISSING:
609 break
610 value = inspect.getattr_static(value, part, _MISSING)
611 return None if value is _MISSING else value
614def _members(found: _Value | _Type) -> dict[str, Item]:
615 if isinstance(found, _Value) and _inspectable(found.obj): 615 ↛ 616line 615 didn't jump to line 616 because the condition on line 615 was never true
616 obj = found.obj
617 return {n: _item(n, inspect.getattr_static(obj, n, None)) for n in dir(obj)}
618 if isinstance(found, _Value):
619 obj = found.obj
620 classes = obj.__mro__ if isinstance(obj, type) else type(obj).__mro__
621 try:
622 # Past any __getattribute__ of the object's own class.
623 own = object.__getattribute__(obj, "__dict__") # noqa: PLC2801
624 except AttributeError:
625 own = {}
626 else:
627 classes, own = found.cls.__mro__, {}
628 members: dict[str, Item] = {}
629 for klass in reversed(classes):
630 for name, annotation in _annotations(klass).items():
631 members[name] = Item(name, "variable", annotation)
632 for name, raw in vars(klass).items():
633 members[name] = _item(name, raw)
634 for name, raw in dict(own).items(): 634 ↛ 635line 634 didn't jump to line 635 because the loop on line 634 never started
635 if isinstance(name, str):
636 members[name] = _item(name, raw)
637 return members
640def _names(namespace: Mapping[str, Any]) -> dict[str, Item]:
641 names = {name: _item(name, value) for name, value in vars(builtins).items()}
642 names |= {name: _item(name, value) for name, value in namespace.items()}
643 names |= {kw: Item(kw, "keyword") for kw in [*keyword.kwlist, *keyword.softkwlist]}
644 return names
647def _item(name: str, raw: Any) -> Item:
648 if isinstance(raw, property):
649 returns = _annotations(raw.fget).get("return", "") if raw.fget else ""
650 return Item(name, "property", returns)
651 if isinstance(raw, (staticmethod, classmethod)):
652 raw = raw.__func__
653 if isinstance(raw, type):
654 return Item(name, "class")
655 if isinstance(raw, types.ModuleType):
656 return Item(name, "module")
657 if isinstance(
658 raw, (types.FunctionType, types.BuiltinFunctionType, types.MethodType)
659 ):
660 return Item(name, "function", _signature(raw))
661 if callable(raw) and inspect.ismethoddescriptor(raw):
662 return Item(name, "function")
663 return Item(name, "variable", type(raw).__name__)
666def _signature(func: Any, *, full: bool = False) -> str:
667 if (inspected := _inspect_signature(func)) is None:
668 return ""
669 text = inspected.format(quote_annotation_strings=False)
670 return text if full or len(text) <= 80 else text[:77] + "..."
673def _inspect_signature(func: Any) -> inspect.Signature | None:
674 try:
675 # As written: evaluating annotations could run code.
676 found = inspect.signature(func, annotation_format=annotationlib.Format.STRING)
677 except TypeError, ValueError:
678 return None
679 params = list(found.parameters.values())
680 if params and params[0].name in ("self", "cls"):
681 # Called on an instance or class, it's never given.
682 found = found.replace(parameters=params[1:])
683 return found
686def matches(name: str, typed: str) -> bool:
687 """`typed` anywhere in `name`, in any case - so `state` finds
688 `async_set_state` - leaving out private names until a `_` is typed."""
689 if name.startswith("_") and not typed.startswith("_"):
690 return False
691 return typed.lower() in name.lower()
694def rank(name: str, typed: str) -> tuple[bool, bool, str]:
695 """Sorting `matches()`: names starting with what's typed first."""
696 return (
697 not name.lower().startswith(typed.lower()),
698 name.startswith("__"),
699 name.lower(),
700 )
703def _matching(
704 members: dict[str, Item], prefix: str, limit: int, clock: _Budget | None = None
705) -> Completions:
706 pairs = members.items() if clock is None else clock.take(members.items())
707 items = [item for name, item in pairs if matches(name, prefix)]
708 # A call's own parameters first.
709 items.sort(key=lambda i: (i.kind != "parameter", *rank(i.label, prefix)))
710 return Completions(items[:limit], len(prefix), len(items) > limit)
713@dataclass
714class Source:
715 """Where something's source is - for `thing??`."""
717 name: str # qualified, `homeassistant.core.HomeAssistant`
718 file: str # "" for something with no Python source, built in
719 line: int
720 url: str # on GitHub, at the version running; "" if not known
722 def as_dict(self) -> dict[str, Any]:
723 return vars(self).copy()
726# Where a package's source is on GitHub: repository, the folder the package
727# is in there, and how a version is tagged ("dev" is the default branch).
728_REPOSITORIES = (
729 ("homeassistant_repl", "rhizomatics/homeassistant-repl", "src/", "v{}", "main"),
730 (
731 "custom_components.ha_repl_server",
732 "rhizomatics/homeassistant-repl",
733 "",
734 "v{}",
735 "main",
736 ),
737 ("homeassistant", "home-assistant/core", "", "{}", "dev"),
738)
741def source(
742 expression: str, namespace: Mapping[str, Any], versions: Mapping[str, str]
743) -> Source | None:
744 """Where the source of what `expression` names is, found without
745 running anything - for an instance, its class's. `versions` gives the
746 version of a package _REPOSITORIES knows that isn't in sys.modules to
747 ask, by its name there. None if it can't be followed."""
748 node = _parse(expression)
749 found = None if node is None else _resolve(node, namespace)
750 if isinstance(found, _Type): 750 ↛ 751line 750 didn't jump to line 751 because the condition on line 750 was never true
751 target: Any = found.cls
752 elif isinstance(found, _Value):
753 target = found.obj
754 else:
755 return None
756 target = _defined(target)
757 if isinstance(target, types.FunctionType):
758 module = target.__module__ or ""
759 name = f"{module}.{target.__qualname__}"
760 file, line = target.__code__.co_filename, target.__code__.co_firstlineno
761 elif isinstance(target, types.ModuleType): 761 ↛ 762line 761 didn't jump to line 762 because the condition on line 761 was never true
762 module = name = vars(target).get("__name__", "")
763 file, line = vars(target).get("__file__") or "", 1
764 elif isinstance(target, type): 764 ↛ 773line 764 didn't jump to line 773 because the condition on line 764 was always true
765 module, name = target.__module__, _qualified(target)
766 line = vars(target).get("__firstlineno__", 1)
767 file = (
768 vars(sys.modules[module]).get("__file__") or ""
769 if module in sys.modules
770 else ""
771 )
772 else:
773 return None
774 return Source(name, file, line, _url(module, file, line, versions) if file else "")
777def _defined(obj: Any) -> Any:
778 """What holds the source of `obj`: the function behind a method,
779 property or decorator, an instance's class."""
780 if isinstance(obj, property) and obj.fget is not None: 780 ↛ 781line 780 didn't jump to line 781 because the condition on line 780 was never true
781 obj = obj.fget
782 if isinstance(obj, (staticmethod, classmethod, types.MethodType)): 782 ↛ 783line 782 didn't jump to line 783 because the condition on line 782 was never true
783 obj = obj.__func__
784 while isinstance(obj, types.FunctionType) and "__wrapped__" in vars(obj): 784 ↛ 785line 784 didn't jump to line 785 because the condition on line 784 was never true
785 obj = vars(obj)["__wrapped__"]
786 if not isinstance(obj, (types.FunctionType, types.ModuleType, type)):
787 obj = type(obj)
788 return obj
791def _url(module: str, file: str, line: int, versions: Mapping[str, str]) -> str:
792 path = module.replace(".", "/")
793 rel = next(
794 (end for end in (f"{path}.py", f"{path}/__init__.py") if file.endswith(end)), ""
795 )
796 if not rel: 796 ↛ 797line 796 didn't jump to line 797 because the condition on line 796 was never true
797 return ""
798 for package, repository, folder, tag, branch in _REPOSITORIES:
799 if module == package or module.startswith(package + "."):
800 version = versions.get(package) or _version(package)
801 if not version: 801 ↛ 802line 801 didn't jump to line 802 because the condition on line 801 was never true
802 return ""
803 ref = branch if "dev" in version else tag.format(version)
804 return f"https://github.com/{repository}/blob/{ref}/{folder}{rel}#L{line}"
805 if module.split(".", maxsplit=1)[0] in sys.stdlib_module_names:
806 v = sys.version_info
807 ref = f"v{v.major}.{v.minor}.{v.micro}" if v.releaselevel == "final" else "main"
808 return f"https://github.com/python/cpython/blob/{ref}/Lib/{rel}#L{line}"
809 return ""
812def _version(package: str) -> str:
813 """Home Assistant's version, if it's running here."""
814 const = (
815 sys.modules.get("homeassistant.const") if package == "homeassistant" else None
816 )
817 version = vars(const).get("__version__") if const is not None else None
818 return version if isinstance(version, str) else ""
821@dataclass
822class Doc:
823 """What something is, found without running anything - for Ctrl-Space
824 and `ha-repl inspect`."""
826 name: str # as asked about
827 kind: str # "class", "function", "module", "property" or "instance"
828 type: str # qualified, `homeassistant.core.StateMachine`
829 signature: str = ""
830 doc: str = ""
831 value: str = "" # a plain value's repr, or a container's size
832 # The class that declares or documents this attribute, when that's
833 # what describes it - its docstring says more than the value's type's.
834 owner: str = ""
836 def as_dict(self) -> dict[str, Any]:
837 return vars(self).copy()
840_PLAIN = (str, int, float, bool, bytes, type(None))
843def describe(expression: str, namespace: Mapping[str, Any]) -> Doc | None:
844 """What `expression` names. None if it can't be followed."""
845 node = _parse(expression)
846 if isinstance(node, ast.Attribute) and (prop := _property(node, namespace)):
847 returns = _annotations(prop.fget).get("return", "") if prop.fget else ""
848 owner = _owner(node, namespace)
849 doc = _docstring(prop.fget) or (_mentions(owner, node.attr) if owner else "")
850 return Doc(
851 expression,
852 "property",
853 returns,
854 doc=doc,
855 owner=_qualified(owner) if owner else "",
856 )
857 found = None if node is None else _resolve(node, namespace)
858 if isinstance(found, _Type): 858 ↛ 859line 858 didn't jump to line 859 because the condition on line 858 was never true
859 return Doc(
860 expression, "instance", _qualified(found.cls), doc=_docstring(found.cls)
861 )
862 if not isinstance(found, _Value):
863 return None
864 obj = found.obj
865 if isinstance(obj, (staticmethod, classmethod)): 865 ↛ 866line 865 didn't jump to line 866 because the condition on line 865 was never true
866 obj = obj.__func__
867 if isinstance(obj, type):
868 init = inspect.getattr_static(obj, "__init__", None)
869 signature = (
870 "" if init in (None, object.__init__) else _signature(init, full=True)
871 )
872 return Doc(expression, "class", _qualified(obj), signature, _docstring(obj))
873 if isinstance(
874 obj, (types.FunctionType, types.BuiltinFunctionType, types.MethodType)
875 ):
876 return Doc(
877 expression,
878 "function",
879 _qualified(obj),
880 _signature(obj, full=True),
881 _docstring(obj),
882 )
883 if isinstance(obj, types.ModuleType):
884 return Doc(
885 expression, "module", vars(obj).get("__name__", ""), doc=_docstring(obj)
886 )
887 value = ""
888 if type(obj) in _PLAIN:
889 value = reprlib.Repr(maxstring=200).repr(obj)
890 elif type(obj) in _CONTAINERS:
891 value = f"{len(obj)} items" # an exact built-in: len() runs nothing else
892 declared = mentions = owned_by = ""
893 if isinstance(node, ast.Attribute) and (owner := _owner(node, namespace)):
894 # As the class declares it - `list[SqlTable]` says more than `list` -
895 # and what its docstring says about it.
896 declared = _declared(owner).get(node.attr, "")
897 mentions = _mentions(owner, node.attr)
898 if declared or mentions: 898 ↛ 900line 898 didn't jump to line 900 because the condition on line 898 was always true
899 owned_by = _qualified(owner)
900 return Doc(
901 expression,
902 "instance",
903 declared or _qualified(type(obj)),
904 doc=mentions or _docstring(type(obj)),
905 value=value,
906 owner=owned_by,
907 )
910_CONTAINERS = (list, tuple, dict, set, frozenset)
913def _mentions(cls: type, name: str) -> str:
914 """The paragraphs of a class's docstring that mention its attribute
915 `name` - as `.name` or `name` in backticks - Python having no docstrings
916 for attributes themselves."""
917 mention = re.compile(rf"[`.]{re.escape(name)}\b")
918 for klass in cls.__mro__: 918 ↛ 925line 918 didn't jump to line 925 because the loop on line 918 didn't complete
919 if klass.__module__ == "builtins":
920 break
921 paragraphs = _docstring(klass).split("\n\n")
922 found = [p for p in paragraphs if mention.search(p)]
923 if found:
924 return "\n\n".join(found)
925 return ""
928def _owner(node: ast.Attribute, namespace: Mapping[str, Any]) -> type | None:
929 """The class whose attribute `node` reads."""
930 owner = _resolve(node.value, namespace)
931 if isinstance(owner, _Value): 931 ↛ 933line 931 didn't jump to line 933 because the condition on line 931 was always true
932 return owner.obj if isinstance(owner.obj, type) else type(owner.obj)
933 return owner.cls if isinstance(owner, _Type) else None
936def _property(node: ast.Attribute, namespace: Mapping[str, Any]) -> property | None:
937 """The property `node` reads, if it reads one - for its own docstring."""
938 owner = _resolve(node.value, namespace)
939 if isinstance(owner, _Value): 939 ↛ 942line 939 didn't jump to line 942 because the condition on line 939 was always true
940 obj = owner.obj
941 cls = obj if isinstance(obj, type) else type(obj)
942 elif isinstance(owner, _Type):
943 cls = owner.cls
944 else:
945 return None
946 raw = inspect.getattr_static(cls, node.attr, None)
947 return raw if isinstance(raw, property) else None
950def _qualified(obj: Any) -> str:
951 """A class's or function's full name. Read off the object itself: a C
952 type keeps these out of its __dict__, and on a class or function they
953 run nothing of its own."""
954 module, name = obj.__module__, obj.__qualname__
955 return name if module in ("builtins", None) else f"{module}.{name}"
958def _docstring(obj: Any) -> str:
959 doc = vars(obj).get("__doc__") if isinstance(obj, types.ModuleType) else _doc(obj)
960 return inspect.cleandoc(doc)[:4000] if isinstance(doc, str) else ""