editor support¶
the by language server backs the editor experience: completions, inlay
hints, an outline, and the rest of the language-server protocol. this page
covers the parts that are basedpython's own — the ones you would not find by
guessing from python. for the PyCharm and IntelliJ plugin, see
the intellij plugin
which dialect a document is¶
a document is basedpython or python by its path's extension, whatever the uri's
scheme: untitled:console-1.by and vscode-vfs://github/app/main.by are
basedpython, as app/main.by is, and untitled:script.py is python. a path
with no extension that says — an editor's untitled:Untitled-1 — is the
language the editor opened it in: basedpython (or by) is basedpython, and
python is python
postfix templates¶
writing . after an expression offers a set of templates that rewrite the
whole expression rather than reading as attribute access. accepting .print
on xs replaces xs.print with print(xs):
| template | rewrites x into |
offered for |
|---|---|---|
.print |
print(x) |
|
.not |
not x |
|
.type .repr .str .len |
type(x), repr(x), str(x), len(x) |
.len: what has a length |
.list .set .tuple .dict |
list(x), set(x), tuple(x), dict(x) |
|
.isinstance |
isinstance(x, object) |
|
.par |
(x) |
|
.compl .comps .compg .compd |
a list, set, generator or dict comprehension over x |
what can be iterated |
.return .raise .yield |
return x, raise x, yield x |
|
.if .while |
an if or a while on x |
|
.ifn .ifnn |
if x is None:, if x is not None: |
what may be None |
.with |
with x as name: |
a context manager |
.for .iter |
a for loop over x |
what can be iterated |
.fore .itere .enum |
for index, item in enumerate(x): |
what can be iterated |
.match |
a match |
|
.let .var |
a binding |
these are PyCharm's python templates, under its names, less cast and
main. one that needs something of x is offered only where x's type has
it, and on an expression whose type says nothing, any. the templates from
.return down are statements, so they are only offered where the expression is
the whole statement — f(xs.print) offers .print but not .for. the ones
that open a suite or need a name to bind place the cursor for you, when your
editor supports snippets
each is a completion labelled with its name, for, and the detail postfix,
whose textEdit replaces the whole x.for and whose filterText is that text
a statement that opens a suite continues on a line indented one level past the
line it is written on. an editor indents each new line of a completion as the
line it is accepted on, so the text says only the one level; an editor whose
client says it inserts a completion's text as it is
(completion.insertTextMode: asIs) gets the line's own indentation written in
too, and one that can be told per completion is told
(insertTextMode: adjustIndentation)
.let and .var spell basedpython bindings; the rest are valid python and are
offered in .py files too
set ty.completions.postfixTemplates to false (or
completions.postfixTemplates in the initialization options, for a client that
does not answer workspace/configuration with it) to be offered none of them.
.await is not a template but syntax, and is offered either way
postfix await¶
.await is not a template — it is real syntax, so it
completes as an ordinary word. it appears inside an async def, on an
expression that can actually be awaited
completions¶
every completion carries a textEdit saying what it replaces: what is typed of
the name before the cursor, car in f"{car, all of a string literal before
the cursor, slow-mo in "slow-mo, and more where a completion stands for more,
as a postfix template does for the expression it rewrites. so an editor never
works out the range from its own idea of a word, which inside an f-string is the
whole string token, against which nothing would match. what is typed is matched
against the name, so a completion labelled with more than its name carries the
name as its filterText: inspect.walktree, which completions.importStyle
module writes, matches walktre
smart completion¶
an editor's smart, type-matching completion asks by/smartCompletion, which
takes what textDocument/completion takes and answers a completion list of the
same items, kept to those that fit the type the position expects: an argument
expects its parameter's type, a return what its function declares it returns,
the value of a declared assignment the declared type, and a case pattern the
subject's. a value fits when its type is assignable to the expected one, and a
class or a function when calling it makes such a value, so on draw( for a
draw(shape: Shape) the list is the variables holding a Shape, Shape and
its subclasses, and the functions returning one. a completion of type Any or
Unknown, a function that never returns and a keyword argument's name fit
nothing for certain, and nothing is imported. of nested positions the innermost
decides: in x: int = len( it is len's parameter. the answer is null where
the position expects no type the source states, or Any
the entry point¶
at module level, main completes to the whole entry point
definition, with async main beside it. once the module defines one, the name
completes to it like any other
keywords¶
every keyword a statement may open with is offered wherever it is valid, whether
it is spelled with one word or several. the single words are basedpython's own —
extension, let, var, and init inside a class body — and a construct
spelled with more than one keyword is offered whole: async def, data class,
frozen data class, enum class, override def, static var, and the rest of
the modifiers. the method modifiers only appear inside a class
body, and async for / async with only inside an async def
they are offered at the start of a statement only — after async the plain
def keyword completes the rest
overriding¶
in a class body, every superclass member the class does not define is offered as the whole header an override would be written with:
object's members are left out
the name of a def written in a class body completes the same way, as the rest
of the header: def gre offers greet(self, name: str) -> str:. in a .by
file, taking it also writes override before the def, unless it is there
already
types¶
a type position offers the words basedpython spells types with — literal,
final, dynamic, some, protocol, typeof — and drops the statement
keywords, which never read there. a type parameter offers its
modifiers before the name: in, out, in out, overlapping, reified
common aliases¶
a name that is conventionally an alias of a module completes as that module,
in a file that has not imported it yet. np. offers what numpy has, and
accepting one of those completions writes the import that binds the name:
the alias itself completes the same way — typing n offers np, and taking it
writes import numpy as np
only a module the project actually has is offered, and only where the name is
free: a file that binds np to something of its own means that, and gets
nothing from numpy
the aliases are the ones the python ecosystem already writes — np, pd,
plt, dt, and the rest. a project spells aliases of its own in its
configuration, keyed by the alias:
an alias configured under a name ty already knows replaces it
a name left unimported reports as unresolved, and the quick fix on that diagnostic writes the same import
these are auto-imports, so turning off ty.completions.autoImport turns them
off too
unimported names¶
a name the file has not imported is offered for import only when what you have
typed starts where one of its words does — at its start, after a _, a . or
any other character that is not a letter or a digit, at an upper-case letter that
follows a lower-case one, at the last of a run of capitals that a lower-case letter
follows (set offers HTTPServer), or at a letter that follows a digit (sum
offers md5sum) — and the rest follows in order. ret offers reveal_type and NoReturn to import, but not
secrets or urlretrieve, which merely contain the letters, and which would
otherwise crowd out return and the names in scope
a name the file has not imported still completes past the dot. Asdf. offers
the members of the Asdf an import would bind, and accepting one writes that
import:
a module reads the same way — mod. offers what import mod reaches — and a
longer chain follows every step, so mod.Asdf. lands on those same members. a
package's submodules are among what it offers, and a submodule is imported from
its package, since import pkg.sub binds pkg rather than the sub the file
wrote:
a name that two modules each define of their own is two offers, one per module, each carrying its own import. one class that several modules re-export is a single offer, since the copies would differ only by an import you cannot see
a name the file already binds means what the file says it means and gets
nothing, and a chain that starts from anything but a name — Asdf(). — has no
name for an import to bind. as with any auto-import, the name has to be one you
have begun to write: a bare mod. in a file that never imported mod offers
nothing, because every symbol spelled mod anywhere would qualify
like the aliases above, these are auto-imports, and turning off
ty.completions.autoImport turns them off too
how an auto-import brings in a name from a module the file imports nothing from yet
is ty.completions.importStyle (completions.importStyle in the initialization
options): "from", the default, writes from inspect import walktree and
completes walktree; "module" writes import inspect and completes
inspect.walktree. a module the file already imports is imported from the way the
file does it, whichever is set — a name from a module imported with import is
written through it, and one from a module with a from ... import is added to that
statement. how imports are sorted, grouped and split is not an editor setting: it
is the project's isort configuration, which buff reads and fixes
an import any of these write — a completion's, an unresolved name's quick fix's, a
pasted name's, an inlay hint's, or that of a quick fix the type checker offers with a
diagnostic, such as the typing import of reveal_type — goes where buff check --select I --fix would put
it, so adding one never leaves the block unsorted. it joins its section of the file's first block of
imports (future, standard library, third party, first party, local, or the
sections the configuration defines) in the order isort sorts that section, with a
blank line around a section the block did not have yet, and a member added to an
existing from import is listed where isort orders the members. a new statement,
and a from import a new member makes too long, is wrapped to the line length as
isort wraps it, a section new to the block gets the heading import-heading
configures for it, and two members of a module the file does not import yet become
one from import:
math is imported between json and sys, Path below the collections
import, defaultdict as from collections import OrderedDict, defaultdict, and
attrs below attr. the configuration is buff's own, resolved as buff
resolves it — the closest ruff.toml, .ruff.toml or pyproject.toml with a
[tool.ruff] table, then the user's, then the defaults — so
force-sort-within-sections, from-first, known-first-party, section-order,
no-lines-before, lines-between-types, force-single-line and the rest apply
as they do to buff. the import has to run before the name it binds is used, so a
file whose imports all come after that point, or that has none, still gets it at
the top, below a docstring and any from __future__ import, followed by the blank
lines isort writes after a block. buff sorts each cell
of a notebook on its own, so in a notebook the block an import joins, and the top it
otherwise goes at, are those of the cell the name is used in
names inside a string¶
a name written inside a plain string's braces completes as a name, and taking
one turns the string into the f-string that reads it — the f and the closing
brace are written for you:
the rest of the string is left exactly as it is written, so any other brace in it starts meaning what an f-string reads it to mean once the prefix goes on
a docstring, a case pattern and a str.format template are not offered the
conversion, and neither is a string written where a type belongs: an f-string
is a different thing in each of those places, or no longer legal at all
dict keys¶
the key of a subscript completes from what the dict is known to hold. a
TypedDict's keys come from its type, and a plain dict's from the dict display
the name was bound to: after d = {"alpha": 1, "beta": 2}, d[" offers
alpha and beta
enum members and extensions¶
a bare enum member is offered where the expected type admits one —
the value of a declared assignment, and a case pattern:
attribute completions include the members any extension
block in scope declares on the receiver, alongside the type's own
callables¶
accepting a completion for anything callable writes its parentheses and leaves
the caret between them, ready for the first argument — or after them, when the
callable takes no arguments at all, as cart.total() does for
def total(self) -> int. one whose parameters are all optional still leaves the
caret inside. set ty.completions.completeFunctionParentheses to false (or
completions.completeFunctionParentheses in the initialization options, for a
client that does not answer workspace/configuration with it) to insert the
bare name instead
inlay hints¶
each kind of hint can be turned off on its own through the
ty.inlayHints.<name> setting your editor passes to the server. all default to
on
| setting | shows |
|---|---|
variableTypes |
the type of a variable the source does not annotate |
callArgumentNames |
the parameter each positional argument fills |
inferredRaises |
the exception set of an undeclared def |
inferredVariance |
the variance inferred for a type parameter |
inferredReification |
reified on a parameter the body reifies |
inferredOverride |
override on a method that overrides without saying so |
inferredReads |
the observables a def reads while composing (basedpython-ui) |
parameterStability |
unstable on a composable parameter the runtime cannot compare |
derivedDependencies |
what a derived(...) computation depends on |
inferredInvalidations |
the composables and derived values a state write re-runs |
callTypeArguments |
the type arguments inferred for a generic call |
typeArgumentNames |
the parameter a positional type argument fills |
numericPromotions |
the arms numeric promotion adds to float and complex |
revealedTypes |
what a reveal_type call reveals, and what it narrowed |
implicitParameters |
a trailing lambda's it |
implicitSelf |
the self an init(...) binds |
lambdaParameterTypes |
the type of an unannotated lambda parameter |
inheritedParameterTypes |
the type a parameter takes from the method it overrides |
inheritedParameterDefaults |
the default it takes from that method |
returnTypes |
the return type of a def that leaves it out |
inferredParameterTypes |
the some bound an unannotated parameter takes from its body |
inferredBaseTypeArguments |
the type arguments a generic base takes from its overrides |
propertyTypes |
the type a property leaves to its accessors |
implicitArguments |
the context arguments a call fills |
enumValues |
the value an enum member takes implicitly |
templateBindingTypes |
a django template {% for %} binding's element type |
resolvedTemplates |
the file a django {% extends %} name resolves to |
every hint also carries its setting's name as data.kind —
{"kind": "revealedTypes"} — so an editor can show each kind in its own way,
or only while a key is held, without telling kinds apart by their text. lsp's
own kind is only Type or Parameter, and a revealed list[int] and a
call's [int] differ by a bracket
a hint is shown or hidden by its own setting alone, but one setting also
changes what other hints say: in a .by file, typeArgumentNames names the
type arguments of the types that variableTypes and callTypeArguments hints
show, so x = identity({"a": 1}) is hinted : dict[Key=str, Value=int] with it
on and : dict[str, int] with it off
keeping a hand-aligned block aligned¶
a hint takes up room. drawn after the name, it pushes the rest of the line along
and a column of = the author lined up by hand stops being one:
let a = [1, 2] # let a: list[int] = [1, 2]
let basdf = 1 # unchanged: a hint for a bare literal is suppressed
the editor cannot repair that by narrowing the hint, because the padding the
author wrote can be narrower than the hint that displaced it. restoring the
column means widening the other lines too, and basdf is the line that has to
move — the line with no hint to hang the answer off. so the server answers which
lines were meant to be read together, with by/alignmentGroups:
{
"textDocument": { "uri": "file:///src/main.by" },
"range": {
"start": { "line": 0, "character": 0 },
"end": { "line": 1, "character": 13 }
},
"tabSize": 4
}
tabSize is required. whether two = share a column depends on it as soon as a
tab comes before either, and it is the client's setting rather than anything the
source says, so there is no value the server could assume
the reply is the blocks whose lines the range reaches. gapStart is where the
padding before the = begins and gapEnd is the = itself, so the difference
between them is the room the author left:
[
{
"members": [
{
"gapStart": { "line": 0, "character": 5 },
"gapEnd": { "line": 0, "character": 10 },
"gapStartColumn": 5,
"gapEndColumn": 10
},
{
"gapStart": { "line": 1, "character": 9 },
"gapEnd": { "line": 1, "character": 10 },
"gapStartColumn": 9,
"gapEndColumn": 10
}
]
}
]
gapStart and gapEnd are positions, counted in the negotiated encoding's code
units. gapStartColumn and gapEndColumn are display columns, counted the way a
fixed-width editor lays the line out — a wide character takes two, a combining
mark none, and a tab reaches the next multiple of tabSize. those are the
numbers the grouping itself was decided by, and the ones to lay hints out in
a block is a run of assignments that are siblings in one suite, unseparated by a
blank line, already sharing a column, and padded — at least one of them written
with two or more spaces before its =. that last condition is what keeps
ordinary code out: x = 1 over y = 2 shares a column only because the names
are the same length, and padding those apart would be injecting space the author
never wrote
how wide anything ends up is the editor's to decide, because only the editor
knows which hints are on screen at a given instant — a kind can be switched off,
and push-to-hint draws a hint only while a key is held. what displaces a line is
every hint drawn on it at or before gapEnd added together, which is more than
one hint when the line unpacks: a, b = 1, 2 is hinted after a and again
after b
a block is reported whole even when the range reaches only one of its lines, since the column is sized against every line at once
outline¶
a property is one member in the source, so it is one entry in the outline — not the getter, backing field and setter it lowers into. enum variants and an extension's methods appear under their declarations
an attribute a method assigns on its receiver, self.radius = radius, is a
field of the class, listed after the members the class body declares. the first
assignment is its declaration, and a name the class body declares already is not
listed again
a def decorated @property, @cached_property or @functools.cached_property
is a property, and its @diameter.setter or @diameter.deleter is the same
property given another accessor, not a second member. each document symbol's
detail is what the source writes beside the name, on one line and printed
from the syntax tree rather than copied from the source: a function's
parameters and return annotation, (self, radius: float) -> None, and a class's
bases, (Shape)
inherited members¶
a structure view that shows a class's inherited members asks
by/documentInheritedMembers with the document, once for all its classes. the
answer is every class of the outline, nested ones too, in source order, each by
the selectionRange of its name and with the members it inherits: what each
class of its method resolution order declares, as that class's outline has it,
attributes a method assigns on self among them, from the first class to
declare the name, and none the class declares itself. object's are there,
last. each member is a document symbol of its superclass's file, with its
name, kind, detail (absent where the symbol has none), range and
selectionRange, the uri of that file, and the superclass as containerName
and its module as containerModule, absent for a superclass in a file no module
is imported from:
[
{
"selectionRange": { "start": { "line": 27, "character": 6 }, "end": { "line": 27, "character": 12 } },
"members": [
{
"name": "describe", "kind": 6, "detail": "(self) -> str",
"containerName": "Shape", "containerModule": "shapes.base",
"uri": "file:///src/shapes/base.by",
"range": { "start": { "line": 23, "character": 4 }, "end": { "line": 24, "character": 57 } },
"selectionRange": { "start": { "line": 23, "character": 8 }, "end": { "line": 23, "character": 16 } }
}
]
}
]
the answer depends on every file the classes inherit from, and the server
announces no change to it: a client asks again after any document of the
workspace changes. it is null for a notebook and a template
workspace symbols¶
workspace/symbol gives each python symbol the module and the classes it is
declared in as its containerName, shapes.base.Circle for the method area
of Circle, so that the three areas of a class hierarchy can be told apart.
the attributes a method assigns on self are found as fields of their class
a query with dots in it is a qualified name. its last part is matched against
the symbol's name and the parts before it against what the symbol is declared
in: Shape.describe finds describe in the class Shape, and base.Sq the
class Square of the module shapes.base. every part matches the way a whole
query does, as a subsequence of its letters. the last part before the name
matches what the symbol is directly in, and each part before that something
further out. a name with dots of its own, like a template's base.html, takes as
many of the query's parts as it has
folding¶
textDocument/foldingRange gives every range a kind saying what it folds, so
that an editor can fold some kinds from the start, and the text to show in its
place when that says more than an ellipsis. the kinds LSP defines go to every
client; the others are basedpython's own, and go to a client that lists them in
textDocument.foldingRange.foldingRangeKind.valueSet
| kind | folds | folded to |
|---|---|---|
imports |
a run of imports | import ... |
region |
# region <name> through its # endregion |
the name |
comment |
a run of comments on lines of their own | |
docstring |
a module's, class's or function's docstring | """Its first line...""" |
function |
a function's body, and its signature when that spans lines | |
class |
a class's body | |
string |
any other string literal spanning lines | """...""", with its prefix |
collection |
the inside of a list, tuple, set or dict display, or of a comprehension | |
annotation |
a parameter's or variable's annotation, or what a def returns or raises |
a client that does not list a kind of basedpython's own is told a docstring is a
comment, and is told no kind for the others. an annotation is the one range
that can lie on a single line: it is sent only to a client that lists the
annotation kind and does not set lineFoldingOnly, and not when it begins on the
line a block fold starts on, where it would put a second fold on that line. the text to fold to is sent
to a client that sets foldingRange.collapsedText. other blocks — an if, a
loop, a with, a try — and the arguments of a call fold with no kind
refactorings¶
the server offers refactorings as code actions. each is worked out from what the
checker reads the file to mean, not from its text: inlining x replaces the reads
of that variable, never a same-named parameter of another function, an attribute
obj.x or a keyword argument f(x=1)
a refactoring either keeps the program meaning what it meant or is refused, and a refusal says why. an editor that asks for refactorings explicitly shows the reason; one that asks while the caret moves is only offered what applies
| refactoring | kind | offered on |
|---|---|---|
| inline variable | refactor.inline.variable |
a variable assigned once |
| extract variable | refactor.extract.variable |
a selected expression |
| introduce constant | refactor.extract.constant |
a selected expression of literals |
| introduce parameter | refactor.extract.parameter |
an expression of literals in a def |
| introduce attribute | refactor.extract.field |
a selected expression in a method |
| extract function | refactor.extract.function |
selected statements |
| add return annotation | refactor.rewrite.returnAnnotation |
a def header with no -> |
| convert to data class | refactor.rewrite.toDataClass |
a class header |
| convert from data class | refactor.rewrite.fromDataClass |
a data class header |
| put on separate lines | refactor.rewrite.splitList |
a list not yet one element a line |
| put on one line | refactor.rewrite.joinList |
a list spread over several lines |
invert if condition |
refactor.rewrite.invertIf |
an if with an else |
| apply De Morgan's law | refactor.rewrite.deMorgan |
an and or an or |
| convert quotes | refactor.rewrite.flipQuotes |
a string or bytes literal |
| loop to comprehension | refactor.rewrite.loopToComprehension |
a loop filling an empty collection |
| invert boolean | refactor.rewrite.invertBoolean |
a boolean variable, parameter, def |
an extraction makes up a name, which its user will want to choose. once its
action is resolved, its data says where the name is: rename, a uri and a
range in the document as the action's edit leaves it, at the place the
rewritten code uses the name, where the selection was. an editor applies the
edit and starts renaming there, as TypeScript's refactorings hand over a
rename location:
{ "data": { "rename": { "uri": "file:///src/shapes.by", "range": { "start": { "line": 13, "character": 21 }, "end": { "line": 13, "character": 30 } } } } }
inverting a boolean gives a variable, a parameter or a function the opposite
meaning under a name that says so, and keeps every use meaning what it meant, as
PyCharm's Invert Boolean does for a .py. it is offered on a variable assigned
True or False, a parameter defaulting to one, and a def declared -> bool,
asked about on the declaration or, for a variable, on any use in its file. it
reads every module of the project to answer, so a client asking as the caret
moves, with the trigger kind Automatic, is not offered it. the new name is
not_ before the old one, or the old one without its not_, and is the made-up
name its data hands back for renaming:
ready = True # not_ready = False
if ready and x: # if not not_ready and x:
ready = check() # not_ready = not check()
print(not ready) # print(not_ready)
every read is negated, or loses its not; every value it is given is negated,
a True or a False by flipping it; a parameter's default and the values calls
pass it by keyword are negated; a function returns the negation of each value
and each call of it is negated. its uses in other modules are rewritten too, and
an import of it is only renamed. it is refused where a use could not be kept
meaning the same: a binding that is not an assignment of a value of its own (an
unpacking, an augmented assignment, a loop's target), a value that is not a
bool, whose negation keeps its truth and loses the value, a write to an
attribute, an attribute of a class, a method or a method's parameter, whose
overrides would have to change with it, a parameter some call may pass by
position or by unpacking, a function used other than by calling it, an async
function, whose call is a coroutine, a function defined more than once, each
with returns and parameters of its own, a function with a return of no value
or a yield, an import under another name, whose reads are no use of the name,
one use inside another, and a rewrite that would lose a comment
inlining is offered on the variable's assignment and on any of its reads alike, and
replaces every read either way. the value is parenthesised only where python
would read it otherwise: inlining square = radius ** 2 into math.pi * square
writes math.pi * radius ** 2, and x = a - b into c - x writes
c - (a - b)
moving an expression can change when it runs, so that is what most refusals are
about. a value made of names and literals, and of python's own operators over
builtin numbers and strings — 'hello ' + name of a str — is the same value
wherever it is evaluated, and is inlined into every read. any other value is only
inlined into a single read in the very next
statement, with nothing that could observe the move evaluated before it; an
expression is only extracted above its statement when it runs exactly once each
time the statement does — not in a loop condition, a conditional branch, a lambda
or after a call
while queue.pending(): # extracting `queue.pending()` is refused: it runs every iteration
queue.pop()
what could observe the move is asked of the checker rather than read off the
spelling. an operator of python's own over builtin numbers and strings — +, -
and * over numbers python does not convert to compute them, + joining strings,
the bitwise operators over integers, comparisons — runs no code of the program's
and cannot raise, and nor does reading a module's attribute. an operand counts as
a builtin number or string only where the checker knows it is exactly one: a
literal, a final type such as final int, or a bool. a plain int or str
may be an instance of a subclass, whose operators are the program's own, so a
declared int is not enough. so in scale * math.pi * radius ** 2 the power can
be extracted where scale is a final float in a .by file. in python a float
also admits an int, and an int meeting a float or a complex is not taken
to be quiet, since one too large for it raises OverflowError (10**400 + 0.5);
nor is repeating a string, which raises it for a count too large for an index.
reading an attribute of an instance is not taken to be quiet, since it may be a
property; nor are /, //, % and **, which raise for some operands
a selection may be a run of operands that python groups otherwise: a + b + c is
(a + b) + c, so b + c is no expression of it, and extracting it evaluates
a + (b + c). that is offered when the operator is associative over what the
operands are — +, * and the bitwise operators over integers, + over strings
or over byte strings — and not over floats, which round differently grouped the
other way
with nothing selected, a client that asks for refactor.extract kinds explicitly
(triggerKind: Invoked and only given) is offered an extraction for each
expression around the caret, innermost first, the same expressions
type info lists less a bare name. each action's title names the
expression — Extract variable `value` from `len(items) + 1` — and its
data.range is the expression's range, for an editor that lets its user pick one
and highlights it; when none can be extracted, the innermost one's refusal is the
answer. a client asking as the caret moves is offered no extraction at a caret
adding a return annotation writes the return type the checker infers, importing
what it names. it is refused when that type is partly Unknown — x + y of two
unannotated parameters — since Unknown is no type a program can name, and the
rest of the union would claim more than the body says. an inlay hint's
double-click edit follows the same rule
introducing a parameter adds name=expression to the parameters of the function
the expression is in — last, or before a ** parameter — and reads the parameter
where the expression was, so every call goes on passing what it passed. a default
is evaluated once, when the def runs, so this is offered only for what a constant
can be made of
introducing an attribute assigns self.name = expression above the statement in the
method and reads self.name where the expression was, by whatever name the method's
first parameter has. the name is one the class does not already have, its own or
inherited, and it is refused where an instance takes no new attribute: a class with
__slots__ in its MRO, a frozen data class, an enum, a named tuple, a protocol or a
TypedDict, and in a class method or a static method — __new__,
__init_subclass__ and __class_getitem__ included — or a decorated method,
whose first parameter need not be the instance
extracting statements from a method makes a method of the same class, called through the receiver. what the statements read from the function becomes a parameter, and what they assign that is read afterwards is returned
a constant goes further than a variable: it is bound at the top of the module, so
it is evaluated as the module loads whether or not the expression would have been
evaluated at all. only an expression made of literals that cannot raise is
hoisted, and whether an operation over literals raises is asked of the checker
rather than read off its spelling — 60 * 60 * 24 is offered because ty folds it
to 86400, while 1 / 0 and 1 + "a" are not offered at all
a client that can resolve a code action's edit gets the action without one, and the
edit is computed when the action is chosen — against the document version it was
offered for, and refused as content modified if the document changed since. this
defers sending the edit, not working it out: whether a refactoring applies is
decided by working out the rewrite, so the actions a textDocument/codeAction
reply offers have each been computed to answer it. send only to narrow that —
a request that does not ask for refactor kinds does no refactoring work at all
inverting an if negates its condition and swaps its body with its else's. a
negation takes off a not, swaps and and or by De Morgan's law, and flips a
comparison's operator only where that means the same: is, is not, in and
not in always, == and != between python's own numbers, strings and bytes, and
the orderings between its integers, strings or bytes — not x > 1 is not
x <= 1 for a float that is nan, so a float's comparison is written
not (x > 1). inverting an if and De Morgan's law are refused where a comment
in the condition would be lost. De Morgan's law rewrites not (a or b) as not a and not b, and
a and b as not (not a or not b) where only the truth of it is read — an if, a
while, an assert or a not — or where it is a bool already, since a and b
otherwise evaluates to a or b. converting a string's quotes escapes the new
quote where it appears and unescapes the old one, and is refused for a raw string
holding the new quote, which cannot be escaped. a loop that only adds to a
collection made empty right above it — a list's append, a set's add, a dict's
item assignment, under at most one if — becomes a comprehension, refused where
the loop's variable is read anywhere outside the loop that the loop's binding may
reach — above it on a later round, in a function, or as del (a comprehension
leaves it unbound) — or is declared global or nonlocal, where the loop reads
what it builds, where a function that reads the collection may be called while the
loop builds it, where it has an else, in a class body, where it adds what a
yield evaluates to or assigns its variable or its iterable with a walrus, which
python does not allow in a comprehension, where it has a comment the comprehension
would not keep, where it calls super() without arguments before python 3.12, and
for a dict whose key and value could both have effects, which a comprehension
evaluates in the other order
putting a list on separate lines, or on one, rewrites the innermost list with brackets of its own around the caret — a call's arguments, a definition's parameters, a display's elements — and only the text between its elements. an element is a node of the parse, so a lambda among the arguments keeps its commas. a split list ends with a comma, which tells a formatter it is meant to stay split, and a joined one loses it unless it is a tuple of one. a list with a comment in it is refused, since joining would put what follows the comment inside it
moving a definition¶
a module's top-level function, class or variable moves to another module of the
project with by/moveSymbol, which a code action could not be: the user picks the
target. the definition is cut with its decorators and the comments directly above
it and appended to the target, and what it reads from its old module comes with
it — an import it uses is written in the target too, and dropped from the old module
when nothing else there uses it and no other module imports it from there, and another of the old module's names is imported
from there:
# shapes/util.py # shapes/geometry.py, after moving `area`
import math import math
RATE = 2 from shapes.util import RATE
def area(r): def area(r):
return math.pi * r * r * RATE return math.pi * r * r * RATE
every reference in the project follows it: from shapes.util import area imports
it from shapes.geometry (or, among other names, loses it to a new import),
shapes.util.area reads shapes.geometry.area with import shapes.geometry added,
a module that reached it through from shapes.util import * imports it by name, an
__all__ that listed it moves it, and the old module imports it back when it still
uses it. each import added goes where the project's isort configuration sorts it
the move is refused, with the reason, when the program would not run as before:
- the definition reads a name private to its module,
_SECRET, which nothing outside the module is meant to import — make it public, or move it too - the two modules would import each other, which python cannot load: the old module still uses the definition and the definition reads the old module's names, or the target imports the old module already
- the target binds the name already, or binds a name the definition reads to something else
- the name is bound more than once in its module
- the definition assigns a name of its module through
global, which would name the target's once moved - the definition reads a name its module binds more than once, which an import would see only as it was when imported
- the definition reads an attribute of its module object,
__name__or__file__, which would be the target's - the definition reads a builtin the target binds to something else
- the modules are not the same kind of file: basedpython does not move into python, nor python into basedpython, which reads it differently
by/prepareMoveSymbol takes textDocument and position — in a top-level
definition's name, in a reference to one, or anywhere else in a top-level
definition, its body included, which is then the one moved — and answers {name, kind, module, uri, range}: the name, function, class or variable, the dotted name of the module
it is defined in, and its name's range in the file uri, which need not be the
document asked about; null where there is nothing to move. by/moveSymbol takes
the same and target, the URI of an existing .py or .by file of the project,
and answers {edit, warnings}, a
WorkspaceEdit of changes to every file the move changes and the references it
left as they were, each with its file and line, or {refused, warnings}, the reason
nothing is moved. two edits at one position of a file apply in the order listed
an editor moving into a new module creates it first and reports it with the
protocol's workspace/didCreateFiles, which the server registers for every
.py, .pyi, .by and .byi file and every folder, before it asks: the server
answers from the file system as it last read it, so without the notification a
module made where it had found nothing is refused as a file that does not exist.
workspace/didChangeWatchedFiles reporting it Created does the same
pulling members up and pushing them down¶
a class's members — a method, with the accessors or overloads that share its name,
or a class attribute — move into one of the project's classes it inherits from
with by/pullMembersUp, or into the project's classes that name it as a base with
by/pushMembersDown, a copy into each that does not define the member itself. each
moves with its decorators and the comments above it, reindented for the body it
lands in: attributes before the methods, methods after them, in the order they
were written
a base the class statement names — a mixin, say — is pulled up the same way, out of the class's bases and into the end of the superclass's, as python's own pull members up offers it. it is refused unless the superclass and every class of the project below it still find every name they found in the class they found it in, python can still order each one's bases, the class still reaches the superclass without the base, and the base is bound at the top of the module above the superclass, which is in the class's module
either is refused, with the reason, where the program would no longer mean what it meant:
- pulled up, a member that reads an attribute of
selfthe superclass does not have — which the superclass's other subclasses would miss — unless that is pulled up with it; that callssuper()from a class whose one base is not the superclass; that a class below the superclass would then find in another class than it does, by its method resolution order — another subclass that finds it in a mixin or above the superclass, or the class itself in a class it finds before the superclass; that reads, where the class body evaluates it — a value, a default, a decorator — a name the class body binds that is not pulled with it, or a name bound after the superclass is defined; or that the superclass has already - pushed down, a member something reads off the class itself, or off what may be an
instance of the class rather than of a subclass — another of the class's methods,
through
self, included — or of a class nothing in the project subclasses - a name-mangled
__member, whose name depends on the class it is written in, a method that reads__class__, which is the class it is written in, a member that reads a name one class finds in a scope around it — a function it is defined in, say — and the other finds elsewhere, and, between modules, a member that reads one of its module's own names that the other module would have to import from a module that imports it, or for any reason a moved function is refused for between modules (moving a definition): aglobalwrite, a name its module binds more than once, a private name, an attribute of its module object, a builtin or a name the other module binds to something else. the imports a member reads go with it
override follows the move. a method pulled up where nothing above has its name
overrides nothing there, so it loses the modifier, and the methods of that name
below the superclass now override it and gain one — override def in basedpython,
@override with its import in python. a method pushed down keeps it only where
something above still has the name, and a subclass's own method of that name loses
it once nothing above has the name
by/prepareMoveMembers takes textDocument and position (anywhere in a class)
and answers {class, members, superclasses, subclasses}: the class and the classes
of the project above it, nearest first, and below it, each {name, qualifiedName, uri, range} with range its name; and its members, each {name, kind, detail, range},
kind one of method, classmethod, staticmethod, property and attribute,
or base for a base the class statement names, as it writes it,
detail how the member reads in a list — a method or property as its name and its
parameters as written, on one line, fetch(self, key: str), an attribute as its name;
null outside a class. by/pullMembersUp takes the same position, members, the
names of the members to move, bases, the bases to move, each as listed with kind
base, and target, a superclass's qualifiedName; a request without bases
names its bases among members, each read by the kind by/prepareMoveMembers lists
it with, and a name listed as both is refused. by/pushMembersDown
takes the position and members. both answer as by/moveSymbol does,
{edit, warnings} or {refused, warnings}
extracting a superclass¶
by/extractSuperclass makes a new class, directly above a class in its module,
that takes the class's bases and the members named, and makes the new class the
class's one base:
with SIDES extracted into Polygon, becomes
the new class sits right after the class in its method resolution order, so a moved
member is found where it was found and super() in a moved method starts where it
started. it is refused, with the reason, for a member that reads an attribute of
self the new class would not have (one the class's own methods assign, or a member
left behind), a name-mangled member, a method that reads __class__, which would
be the new class, an attribute of a decorated class (a data
class's field, say), a generic class, a class whose base python treats specially —
Protocol, NamedTuple, TypedDict, Generic, an enum — a class that passes a
keyword other than metaclass when it is made, a name that is not an
identifier or is a keyword, and a name the module binds already. it takes textDocument, position (anywhere in the class),
members, the names to move, as by/prepareMoveMembers lists them, and name,
and answers as by/moveSymbol does
changing a signature¶
by/changeSignature gives a function a new parameter list — parameters added,
removed, reordered, renamed, given or stripped of defaults or annotations, moved
between kinds — and rewrites every call of it in the project to pass them. it can
rename the function too, wherever the project refers to it, imports included, and
give it a new return annotation. each call is bound the
way python binds it, its positional arguments to the positional parameters and its
keywords by name, and written again for the new list: by position while the
parameters still line up, by keyword after that, a keyword staying a keyword, and
keywords in the order the call wrote them. a new parameter is passed the value
given, or left to its default. a renamed parameter is renamed where the body reads
it and where calls pass it by keyword, and a method's calls through an instance and
through its class keep their receiver. calls through a name an import gives the
function, from m import area as a, are rewritten too. where the new order would
evaluate an argument before one written before it and either could change what
the other does, the call passes them by keyword in the order it wrote them
def area(width, height=1, *, scale=1.0): ... # (height, width, *, scale=1.0)
area(2, 3) # area(3, 2)
area(2, height=3, scale=2.0) # area(width=2, height=3, scale=2.0)
it is refused, with the file and line, where a call cannot be rewritten to mean what
it meant: a call that unpacks *args or **kwargs into the function, unless every
existing call stays valid as it is (a parameter added with a default after the others
leaves them all alone; one added before **kwargs does not, since it could take a
keyword); an argument the change would drop when evaluating it could have an
effect; an argument whose order of evaluation cannot be kept because it is only
taken by position; a keyword a call passes into **kwargs that a parameter of the
new list would take; a call with nothing to pass for a
parameter without a default; the function used other than called, unless every call
stays valid. and where the result would not be python, or not the same program: a
removed parameter the body still reads, a parameter without a default after one with
a default, two of one name, kinds out of order, or a method another class of the
project overrides or that overrides another's, whose signatures would part. a new
name that is not an identifier, is a keyword or is bound already in the scope the
function is defined in is refused, and so is a default, a value or an annotation that is not one expression
where it is written. also refused are a new parameter name the body already binds
or reads from outside the function, a function its decorators bind to something
other than itself, and one defined more than once where it is defined, as an
@overload set is
by/prepareChangeSignature takes textDocument and position — in a function's
name or parameters, or in a name that refers to it — and answers {name, uri, range, parameters, returns}, returns its return annotation as the source writes it or null, and its parameters each {name, kind, default, annotation} with kind
one of positionalOnly, positionalOrKeyword, variadic (*args), keywordOnly
and variadicKeyword (**kwargs), and default and annotation as the source
writes them; a method's self or cls is not listed and stays as it is.
by/changeSignature takes the same position, name?, the function's new name, absent
to keep it, parameters, the whole new list in order, each
{name, oldName?, kind, default?, annotation?, value?}, and returns?: oldName the
parameter it was, absent for a new one; default written as source, absent for
none; annotation and returns written as source, null to remove the one there
is, and absent to keep it (none, for a new parameter); value what each call passes
a new one. it answers as by/moveSymbol does, {edit, warnings} or
{refused, warnings}
unwrap and remove¶
by/unwrap answers what an editor's unwrap/remove offers around a range, innermost
first: each if, loop, try or with around it can be replaced by one of its
suites, dedented to where the statement stood, and each elif, else, except or
finally the range is in can be removed. a try unwraps into the path that raises
nothing — its suite, then its else, then its finally
these change what a program does, which is what they are asked for, so they are
not refused for that. they are refused when the result would not say what it seems
to: a loop whose body breaks or continues does not unwrap, since the jump would
leave some other loop or none, a try keeps an except or a finally, and a
try with a finally does not unwrap when its suite can return, raise,
break or continue, since the finally would no longer run after it. comments
after a kept suite's last statement go with the suite
each option comes with the range it rewrites and the ranges of it that stay, for an editor to mark the one selected, and its edits are many small ones — the header deleted, each line of a kept suite dedented — so the caret stays where it was in the text. the lines of a string literal that spans several lines are left as they are, because their indentation is part of the string
semantic tokens¶
the legend initialize answers with, in its order — a token's type and
modifiers are sent as positions in these lists. the names LSP defines are used
where one fits; the others are basedpython's own
| token type | what it is |
|---|---|
namespace |
a module |
class |
a class, or a type alias |
parameter |
a parameter, and the name a keyword argument is passed by |
selfParameter |
a method's self |
clsParameter |
a class method's cls |
variable |
a variable or an attribute |
property |
a property |
function |
a function |
method |
a method |
keyword |
a keyword spelled like a name (var, let, typeof), and a directive of a format spec or a strftime format |
string |
a string literal |
number |
a number literal |
decorator |
a decorator's name |
builtinConstant |
None, True, False |
typeParameter |
a type parameter |
comment |
a comment in a django template |
operator |
punctuation in a django template or in a script's # /// script metadata |
regexp |
a date or time in a script's # /// script metadata |
punctuation |
a bracket, a comma, a colon, a semicolon or a dot in unreachable code, for a client that asks; see below |
| modifier | the token is |
|---|---|
definition |
where the name is defined, rather than used |
readonly |
a name written as a constant, MAX_SIZE, or a property with no setter |
async |
the name of an async def where it is defined |
documentation |
a docstring (on a string) |
defaultLibrary |
a name the builtins module defines — print, len, str — or a django builtin |
functionScope |
a name bound in the scope of a function, a lambda or a comprehension |
annotation |
part of a type expression |
dunder |
a dunder name, __init__ or __name__ |
keywordArgument |
the name a keyword argument is passed by, scale in total(scale=2.0) |
unreachable |
inside code reported as unreachable, for a client that asks; see below |
functionScope marks a parameter or a local, as against a module global or a
class attribute. it is the binding that decides, not where the name is written:
a global read inside a function is not marked, a nonlocal name is, and an
assignment expression in a comprehension at the top of a module binds a global.
a def or a class nested in a function is a local too, and its name is marked
where it is declared as well as where it is used. an editor that colours each
local by its name ("rainbow" highlighting) reads it off this modifier
a name is a method where the def it names is made in a class body, wherever
the name is used: field called in a dataclass's body is a function, the one
dataclasses defines
annotation marks every token of a type expression: a parameter's or a
variable's annotation, what a function returns or raises, a type alias's value,
a type parameter's bound or default, and an argument the checker reads as a type,
as cast(list[int], x) does its first. a default value is not one. dunder
marks a dunder wherever it is defined or read; a name that only starts with
underscores is not one
three experimental client capabilities, each true or left out, change which
tokens are sent, for an editor that draws something else in their place:
| capability | changes |
|---|---|
experimental.languageInjection |
leaves out the string token of a fragment by/injections reports, which the editor highlights in the fragment's language |
experimental.unreachableWithoutSemanticTokens |
leaves out every token inside a range reported as unreachable code |
experimental.unreachableSemanticTokenModifier |
marks every token inside a range reported as unreachable code with the modifier unreachable, and adds one for each part of that code that had none |
the ranges the last two act on are exactly the ranges of the unreachable-code
hints, the parts of a statement included — in print(exit()) they are
print( and ), and exit is left as it is. both are honoured by
textDocument/semanticTokens/full and textDocument/semanticTokens/range; the
server offers no delta requests
unreachableWithoutSemanticTokens is for an editor that greys unreachable code
with a colour of the same weight as a token's, where the token's colour would
otherwise win: of an unreachable print(1) only the parentheses would be grey
unreachableSemanticTokenModifier is for an editor that fades unreachable code
in its own colours, and finds the colour of a token by its type and the fading
by the modifier. so that every character of the code can be faded, a part that
has no token otherwise gets one: a keyword such as return a keyword, an
operator an operator, a comment a comment, a name a variable, and a
bracket, a comma, a colon, a semicolon or a dot a punctuation, which is
basedpython's own type, since none of them is an operator. a client that asks
for both gets the marks
an editor that fades the code over the tokens it already has, as VS Code does, asks for neither
keyword highlighting¶
textDocument/documentHighlight on a keyword answers the keywords that belong
with it rather than the occurrences of a symbol: the elifs and else of an
if, the except, else and finally of a try, the returns of a def.
the pairing is read off the parse tree, so match = 1 is an assignment and
nothing lights up on it. a position that is not a keyword is answered the way it
always was
typing a clause¶
a clause that continues a compound statement — elif, else, except,
finally, a further case — belongs at the indentation of the clause it
continues, and an editor starts a new line at the indentation of the body it
closes. the server advertises textDocument/onTypeFormatting with : as its
trigger, and answers the : that finishes such a header with the edit that
moves the clause out:
for item in items:
if item:
handle(item)
else: # typed here, moved out to the `if` when the `:` goes in
the statement it moves to is the innermost one still open above the line that
can take that clause next and is not indented deeper than the line already is.
a clause is only ever moved out, so an else: typed at the loop's column stays
with the loop, and an if that already has its else is passed over. which
statements are open is read from a parse of the text above the line alone,
since the clause itself is a syntax error until it is where it belongs. a :
that does not end the header — in a slice, a dict or a lambda — and
case: int = 1, an annotated variable called case, are answered with no edit
completing a statement¶
by/completeStatement finishes the statement at a position and starts the line
after it, which is what an editor's complete current statement does:
{
"textDocument": { "uri": "file:///src/main.by" },
"position": { "line": 1, "character": 10 },
"options": { "tabSize": 4, "insertSpaces": true },
"textHash": "…"
}
a single-quoted string left open on the line is closed, the brackets left open
on it are closed innermost first, a clause header gets its : — and a def
its () — and a clause that continues a compound statement is moved out the
way typing its : moves it. a statement carried on to lines below that parse,
such as a call spread over several lines, is completed where it ends rather
than on the line asked about; a bracket the following lines do not close is
closed where it was left open. the new line goes inside the suite a header
opens, at the indentation of the suite's statements when it has some already
and one level deeper than the header otherwise, and after any other statement
at the statement's own indentation. options says what one level is, the way
textDocument/onTypeFormatting does: tabSize spaces, or a tab
the reply is the edits, against the document as it was asked about, and where the caret goes in the document as the edits leave it:
{
"edits": [
{
"range": {
"start": { "line": 1, "character": 10 },
"end": { "line": 1, "character": 10 }
},
"newText": "):\n "
}
],
"caret": { "line": 2, "character": 8 }
}
like the other document requests it takes textHash, and it is null when
language services are off
writing a docstring¶
typing """ and Enter at the top of a function's body leaves an empty docstring,
and an editor asks by/docstringStub with a position inside it for the stub to
fill it with:
{
"textDocument": { "uri": "file:///src/shapes.by" },
"position": { "line": 2, "character": 11 },
"format": "google"
}
the answer replaces the whole literal, quotes and prefix kept, and says where the
caret goes in the document once newText is in it — the summary line, which is
written indented and empty:
{
"range": { "start": { "line": 2, "character": 8 }, "end": { "line": 2, "character": 14 } },
"newText": "\"\"\"\n \n\n Args:\n item:\n\n Returns:\n \"\"\"",
"caret": { "line": 3, "character": 8 }
}
the stub lists every parameter but a method's receiver — the instance or class
a method is passed, and the class __new__ is — with *args and **kwargs, and
says what the function hands back: Yields for a generator, Returns when its
annotation is something other than None, NoReturn or Never, or with no
annotation when it returns a value. format is rest (:param item:),
google, numpy or plain (the summary alone); without one, the format is the
one the file's other docstrings are written in, and reStructuredText, as PyCharm
writes by default, when none of them says. the answer is null anywhere that is
not inside a triple-quoted docstring of a function holding nothing but whitespace
on a line of its own
rules¶
each diagnostic names the rule it is reported under as its code,
unresolved-reference. an editor that gives every rule an entry of its own, an
inspection whose severity its user can change, asks by/rules, with no
parameters, for the rules before any diagnostic arrives. the answer is every
rule, by name, each with its one-line summary, its defaultLevel (ignore,
warn or error), the level it has when the configuration names no other, and
its status (stable, preview or deprecated):
[
{ "name": "unresolved-reference", "summary": "detects references to names that are not defined", "defaultLevel": "error", "status": "stable" }
]
a removed rule is left out. by/explainRule gives a rule's whole
documentation, and the linter's rules, F401 among them, are buff's. rules
have no categories
a console's input¶
a console running by repl asks by/inputStatus, with the text
typed so far as text, whether enter runs it or starts another line of it. the
answer's status is complete, incomplete — a compound statement whose body
could still go on, an open bracket, an unterminated triple-quoted string, a line
continued with \ — or invalid, input no further line can make valid, which
runs to report why. it is the answer by repl gives itself for the lines it
reads, and needs no document open
what by takes on its command line¶
an editor starts by itself for some things — a console's by repl, a run
configuration's by run — and has to know which of their flags the by it has
takes. the language server is that by, so initialize answers it under
experimental, rather than the editor running by to read its --help: each
command by name, and each flag the editor can start it with by its long name in
camelCase, true
{
"repl": { "events": true, "module": true, "sessionFile": true },
"run": { "coverage": true, "inBuild": true, "launcher": true, "profile": true }
}
sessionFile is --session-file. a flag that is not named — or an answer with
no experimental at all, from a by before this — is one this by does not
take
completing by in a terminal¶
an editor that completes by typed in its terminal asks by/commandLine, with
no parameters, for the whole command line: every command and argument --help
shows, described from the parser by parses its own arguments with, so the
answer is always the command line of the by the server is. a command has its
name, its aliases, its one-line help, its options, its positionals and
its subcommands, each a command again:
{
"name": "run",
"aliases": [],
"help": "Transpile and run a module with `python -m <module>`.",
"options": [
{ "long": "python", "short": null, "aliases": [], "help": "…",
"value": { "name": "PATH", "kind": "path", "hint": "any" }, "repeatable": false },
{ "long": "compiled", "short": null, "aliases": [], "help": "…",
"value": null, "repeatable": false }
],
"positionals": [
{ "help": "…", "value": { "name": "MODULE", "kind": "module" },
"required": false, "repeatable": false, "trailing": false },
{ "help": "…", "value": { "name": "ARGS", "kind": "text" },
"required": false, "repeatable": true, "trailing": true }
],
"subcommands": []
}
an option with no value is a flag. a positional that is trailing takes
everything after it, options included: after by run's module, those are the
arguments of the program it runs, which by does not interpret. a value's
kind says how to complete it:
module— a module of the project by its dotted name: eachmoduleof themodulesby/runModulesanswers for the project the terminal is inrule— a rule by its name, eachnameby/rulesanswers, orallpath, with ahintofany,file,directoryorexecutable— a path, which the editor completes from the file systemchoice— one of itschoices, each anameand itshelptext— anything, which nothing completes
no argument of by's own takes a test id: the node ids by/testItems answers
are pytest's, which a program by run runs is handed among its own arguments
suppressing a diagnostic¶
every diagnostic has two quick fixes that silence it rather than fix it.
ignore for this line writes # ty: ignore[<rule>] at the end of its line,
and ignore in this file writes it on a line of its own at the top of the
file, before any code, which suppresses the rule throughout the file. a
suppression already there takes the rule instead of a second comment being
written, and a #! line stays first. ty has no suppression that covers one
function or one class, so neither does the editor
hover¶
a hover opens with what the name is: its kind and the dotted name it is
reached by from outside its module, method shapes.base.Circle.area. the kinds
are module, class, function, method, property, attribute (a name a
class body binds, or one a method assigns on self), variable, parameter,
type parameter and type alias. a name local to a function has only its own
name, and so does a parameter or a type parameter
a decorated def is shown as its source writes it, its decorators over its own
signature and with its own docstring:
and the docstring is the def's, not that of the type its decorators bind the name
to. when that type is not the def's own function, which for a decorator returning
a wrapper of its own is def wrapper(*args, **kwargs), it is shown first, before
the def as written. that holds wherever the name is hovered, a call of it included,
except a use of a property, which reads the property's value
what a name declares¶
an editor's copy reference copies a declaration's dotted name, and a search
for usages names what it searched for. both ask by/declaration, with the
position of a name where it is declared or where it is used:
and the answer is what the name declares, or refers to, and where:
{
"kind": "method",
"name": "area",
"qualifiedName": "shapes.base.Circle.area",
"originSelectionRange": {
"start": { "line": 3, "character": 14 },
"end": { "line": 3, "character": 18 }
},
"uri": "file:///src/shapes/base.by",
"range": {
"start": { "line": 4, "character": 4 },
"end": { "line": 5, "character": 26 }
},
"selectionRange": {
"start": { "line": 4, "character": 8 },
"end": { "line": 4, "character": 12 }
}
}
kind is one of the kinds a hover names. qualifiedName is the module's
dotted name, each class the declaration is made in, and the name; an attribute
a method assigns on self is the class's, shapes.base.Circle.radius. it is
null for a name local to a function, a parameter, a type parameter, and a
declaration in a file no module is imported from. originSelectionRange is the
name at the position, range the whole declaration and selectionRange its
name. a called class is the class, not the __init__ the call runs, and a
decorated def is the def. the answer is null where there is no name, and
for a name whose definitions declare different things
what each usage does¶
an editor's find usages groups the usages of a name by what each does with
it, as PyCharm's Python groups them: the imports of a class apart from its uses
as a base and in annotations. a Location has nowhere to say that, so
by/references takes what textDocument/references takes, a position and
context.includeDeclaration, and answers the same references in the same
order, each with its kind:
[
{ "uri": "file:///src/shapes/util.by", "range": { "start": { "line": 0, "character": 31 }, "end": { "line": 0, "character": 36 } }, "kind": "import" },
{ "uri": "file:///src/shapes/util.by", "range": { "start": { "line": 3, "character": 25 }, "end": { "line": 3, "character": 30 } }, "kind": "typeHint" }
]
| kind | the reference is |
|---|---|
import |
in an import or from ... import statement |
isinstance |
among the classes an isinstance call tests against: its second argument, or in a tuple there |
typeHint |
in a type expression: an annotation, a return or raises annotation, a type alias's value, a type parameter's bound or default, or an argument a call takes as a type, such as cast's first |
superclass |
in the parentheses of a class's header, a base or a keyword such as metaclass= |
write |
binding the name: an assignment, an augmented assignment, a del, a for or with target |
read |
reading it, which calling it is |
declaration |
the name where it is declared, there with includeDeclaration |
a reference is the first of these that holds, from the top, so an import is an
import although it binds the name, and of nested groups the nearest wins: a
class in cast's first argument in a base list is a typeHint. the answer is
null where textDocument/references answers null
without includeDeclaration, both leave out only where the name is declared, in
the scope that declares it: its def or class, an annotation of it, or an
assignment no other assignment of it comes before. what binds it anywhere else
stays, as PyCharm's Python lists it: an import of it, an assignment to it
through its module or through an instance, from another method than the one
that declares the attribute, or from a function naming it global. an import
names the name without using it, so the usage counts leave it
out; the writes are uses, and are counted
type info¶
an editor's type info shows the type of an expression, and which expression
is meant depends on more than the name under the cursor: on text in
len(text) + 1, a reader may be asking about text, about len(text) or about
the sum. the editor asks by/expressionTypes with the selection, or an empty
range at the caret:
{
"textDocument": { "uri": "file:///src/main.by" },
"range": {
"start": { "line": 1, "character": 17 },
"end": { "line": 1, "character": 17 }
}
}
and the answer is every expression of the statement that contains the whole
range, innermost first, each with its range, its type as the document's
language spells it, on one line, and the same type pretty, written for a
reader:
[
{ "range": { "start": { "line": 1, "character": 15 }, "end": { "line": 1, "character": 19 } }, "type": "str", "pretty": { "language": "python", "value": "str" } },
{ "range": { "start": { "line": 1, "character": 11 }, "end": { "line": 1, "character": 20 } }, "type": "int", "pretty": { "language": "python", "value": "int" } },
{ "range": { "start": { "line": 1, "character": 11 }, "end": { "line": 1, "character": 24 } }, "type": "int", "pretty": { "language": "python", "value": "int" } }
]
pretty is written as hover writes a type: a function's parameters one to a
line once there is more than one, and each signature of an overloaded function
after the one before, as the def it declares — so print, whose type is
Overload[(*values: object, sep: str | None = " ", …) -> None, (…) -> None],
is
def print(
*values: object,
sep: str | None = " ",
end: str | None = "\n",
file: SupportsWrite[str] | None = None,
flush: Literal[False] = False
)
def print(
*values: object,
sep: str | None = " ",
end: str | None = "\n",
file: SupportsWriteAndFlush[str] | None = None,
flush: bool
)
it is LSP's MarkedString in its { language, value } form: language is
python, which the value can be highlighted as, or xml for a special type
such as <special-form 'typing.Any'>, which python highlighting renders poorly.
a type short enough for one line is the same in both
with a selection the first is the smallest expression containing it, which is
the selected one when the selection is exactly an expression. the targets a
value is unpacked into, kind, _, size in kind, _, size = spec.partition(":"),
are the tuple of what each is bound to, (str, str, str), a starred one standing
for any number of its list's elements. an expression ty has no type for, such as
one inside a string annotation, is left out. the answer
is an empty list where the range is in no expression, a def's name or a
keyword, and null when language services are off
extend selection¶
textDocument/selectionRange grows a selection the way a reader reads the
code, not only node by node. on "a" in xs = ["a", "b"] the ranges are the
string's text, the string, "a", with its comma and the space after it, "a", "b" without the
brackets, the list, the assignment, and then the assignment's whole line. a
last element takes the comma before it, , "b". a statement is offered as the
whole lines it is written on, indentation and newline included, when it shares
them with nothing but a comment, and the statements of a body are offered
together without their header, so a selection inside a method grows to the
method's body, then to the method with its decorators as whole lines, then to
the class
go to declaration¶
textDocument/definition and textDocument/declaration on the name of a
called class go to the constructor the call runs: on Circle in Circle(3),
the __init__ (or __new__) that Circle writes, or that the base it
inherits one from writes. a call of a class is a call of its constructor, and
the constructor is where its parameters are. a class that writes none, and so
runs object's, goes to the class. the class itself is always a
textDocument/typeDefinition away, and a rename or a search for references
from the same name is about the class
go to super¶
textDocument/implementation on a method goes down, to the methods that
override it. a decorated override is its own def, not the function its
decorator returns, which a decorator like logged, returning a wrapper of its
own, defines somewhere else. by/superMembers goes up: given a position on the name a class
member is declared with — a def or a nested class, a name the class body
assigns, annotates or captures, or an import's alias — it answers the
superclass members that member overrides, each with its class, its file and the
name to land on. a class goes up with by/mro
by/mro takes a position on a class's name, where it is declared or used, as
textDocument/prepareTypeHierarchy does, and answers every class it inherits
from in python's lookup order, its method resolution order without itself:
Shape, ABC, object for class Circle(Shape) with class Shape(ABC), and
a diamond's shared base after both its sides. each is a type hierarchy item as
typeHierarchy/supertypes answers one, which gives only the direct bases. the
answer is null where there is no class
what counts as an override is the override checks' own walk up the MRO, from
the class as it is written rather than as a decorator returns it. of what that
walk finds, a member goes to the nearest declaration along each branch, in MRO
order: a method overriding B.f, where B.f overrides A.f, goes to B.f,
and a class with two bases that each declare the method goes to both. the first
of them is the one missing-override-decorator names. a private member
overrides nothing, since it is emitted under a name of its own, and a member a
superclass synthesizes rather than writes — a dataclass's __init__ — goes to
that superclass, marked synthesized. each is marked abstract when it is
abstract where it is declared — an @abstractmethod, or a protocol method with
no implementation — so that a member overriding it implements it. the answer is
null when no class member is declared at the position, and an empty list for
one that overrides nothing
an answer depends on more than the text of the document it is about: on every
file the document's classes inherit from, and the server announces no change to
it. a client that keeps one asks again after it opens, edits or closes any
document of the workspace, not only that one, and on
workspace/inlayHint/refresh, which the server sends, to a client that supports
it, after a change on disk or to the environment changes what it answers from
by/documentSuperMembers answers the same for a whole document in one request,
from the same code: every class member that overrides something, with its
class, the range of the name it is declared with, whether it is abstract
itself, and its superMembers as by/superMembers gives them. it is what an
editor asks to draw an "overrides" marker beside each member, on every pass over
the document. a property with get and set blocks is one member, listed once.
constructors and the methods they call — __init__, __new__,
__post_init__, __init_subclass__ — are left out, since neither
invalid-method-override nor missing-override-decorator holds one to what it
overrides, and by/superMembers still answers one. like the other document
requests it takes textHash, and answers a document the client has not opened
from the file on disk
usage counts¶
by/documentUsageCounts answers, for a whole document, how many places use
each of its declarations and how many classes subclass it or members override
it: what an editor draws above each one as "3 usages" or "2 overrides". the
declarations are the document's outline at the depth a reader scans a module
at — its classes and functions, and the methods and properties of those
classes. a dunder method such as __eq__ is there for what overrides it, but
its usages are not counted, the language calling it rather than its name: it
has no references, even when they are asked for. a constructor and the
methods it calls, __init__, __new__, __post_init__ and
__init_subclass__, are left out, as by/documentSuperMembers leaves them
out: a subclass's constructor takes what its own class needs, so it overrides
nothing and nothing overrides it. a module's dunder function is left out, and so
is an extension block, which names a class it does not declare
each declaration comes with its name, its kind (class, function or
method), its whole range from its first decorator, its selectionRange on
its name, and the counts named in the request's counts:
| count | what it is |
|---|---|
references |
the places by/references finds from the name, the declaration not among them, less those of kind import |
implementations |
of a class or a method, what textDocument/implementation finds from the name, less itself |
so the count is the number of places the click on it goes to, when a client
sends that request from the name, but for the imports: an import names the
declaration without using it, so find usages lists it and the count leaves it
out. every declaration has abstract, true for a
method with implementations that is an @abstractmethod or a protocol member
with no body, so that what overrides it implements it, and false otherwise. a count not named is not worked out
with implementations comes implementors, the places it counts, in the
order textDocument/implementation answers them, so that an editor can say
"is overridden in Circle, Square" without asking. each is a subclass of the
class, or a member overriding the method, with the uri, range and
selectionRange it is declared at and the class it is in: className, the
subclass itself or the class whose member overrides, absent for an
implementation in no class, and qualifiedName, that class's dotted name,
shapes.base.Circle, absent for a class local to a function or in a file no
module is imported from
{
"name": "area", "kind": "method", "implementations": 1, "abstract": true,
"implementors": [
{
"className": "Circle", "qualifiedName": "shapes.base.Circle",
"uri": "file:///src/shapes/base.by",
"range": { "start": { "line": 32, "character": 4 }, "end": { "line": 34, "character": 41 } },
"selectionRange": { "start": { "line": 33, "character": 8 }, "end": { "line": 33, "character": 12 } }
}
]
}
each count is a search of the workspace, made for all the declarations of the document in one pass: each file is read once, and searched for each declaration whose name it holds. the searches run one at a time, on a thread of their own, so however many a client has asked for, the requests someone is waiting on, such as a hover or a completion, never queue behind them. a count the client cancels stops where it is, its work in parallel included, so a client that asks again on every edit and cancels the ask the edit made stale leaves no searches running behind it
a count depends on every file of the workspace, and the server announces no
change to it: a client asks again after any document of the workspace changes,
and asks for every count it draws in one request. it is not a
textDocument/codeLens, since a client that draws lenses asks for them again
only when their own document changes. like the other document requests it takes
textHash
tests and what they test¶
by/testSubjects and by/subjectTests answer an editor's go to test subject
and go to test. a test exercises what it calls, as call hierarchy sees a call:
a function or a method called by name or as an attribute, or a class
constructed. which declarations are tests is pytest's collection, as
by/testItems reports it. nothing goes by file names: test_circle.by tests
whatever it calls, wherever that is, and the tests of a class are found whatever
their files are called
by/testSubjects takes a position in a test, in a class tests are collected
under, or anywhere else in a module tests are collected from, standing for that
test, every test under the class, or every test in the module. it answers the
project's own functions, methods and classes those tests call, each once, in the
order they are first called: not what is declared in a test module or a
conftest, and nothing outside the project. each item has its name within its
module with the classes it is declared in (Circle.area), its kind, its
module, and its uri, range and selectionRange. the answer is null for
a document no test is collected from
by/subjectTests takes a position in a function, a method or a class, or
anywhere else in a module, which stands for every function and class it
declares; a class stands for itself and its methods. it answers the collected
tests that call it, as items named by their pytest node id after the file
(TestCircle::test_radius), by file and then in source order, and newTest,
where a test of it would go: test_ and the last part of its module's name, in
the directory most of the project's test modules are in, or in tests under the
project root when there are none. a test module of that name there already is
the one, whether it is .by or .py; a new one is written in what the subject's
file is. newTest says whether that module exists, the module to import
from, the name to import (absent for a module, which a test imports whole), a
testName the module does not define already, and for a module that exists the
importEdits that import the name into it, none when it does already. newTest
is null for a test module, or a module with no name to import it by. like the
other document requests both take textHash, and with it answer a document the
client has not opened from the file on disk
by/moduleName takes the uri of a file or a directory and answers the dotted
name it is imported by, from the search path it is under: a src-layout
project's src/shapes/circle.by is shapes.circle, and src/shapes and
src/shapes/__init__.by are both shapes. it is null for a path no module is
imported from, and for a file that resolution would never reach
running tests in an IDE¶
by run pytest reports to an IDE's test runner when BY_TEST_REPORTER=teamcity
is set: the pytest plugin by run puts in the tree writes the run to standard
output as TeamCity service messages, alongside pytest's own output, which is left
as the arguments ask for. what it writes:
enteredTheMatrixas the session starts, so a client knows the plugin is reporting before the first test, andtestCountwith how many tests were collected- a file that failed to collect, a test module whose import raised, as a test of
its own at the top level, named by its file:
testStarted,testFailedwith the error's line asmessageand the whole report asdetails, andtestFinished; a file skipped as a whole hastestIgnoredinstead - for each test, the suites it is in: its file, named by the project file it was
transpiled from or copied out of relative to the project,
tests/test_calc.by, and each class it is collected under,TestGroup, each opened before the first of its tests and closed after the last testStartedwith the test'snameas pytest gives it,test_sumortest_add[1-2], its node id asmetainfo,tests/test_calc.py::test_sum, which is what pytest is given to run it again, andcaptureStandardOutputfalsewhile pytest captures its output, which follows astestStdOutandtestStdErrtestFailedwhen any of its setup, call or teardown failed: the error's line asmessage, prefixederror at setup:orerror at teardown:for those, and pytest's report of the failure asdetails, every frame at its.byline. when the failure is an assertion that failed comparing two values with==, and that comparison is the one it made, it carriestype='comparisonFailure',actual, the left side, andexpected, the right side, each a string as it is and anything else aspprintwrites it.assert a == b or c == dcarries neithertestIgnoredfor a test skipped, with the reason, or failing as expected, withexpected failure:and the reason, thentestFinishedwith itsdurationin milliseconds
every locationHint is file:// and the absolute path of the project file, with
: and the 1-based line of the def or class for a test or a class. any other
value of BY_TEST_REPORTER is refused as a usage error
endpoints¶
by/endpoints answers an editor's endpoints view: every HTTP route the project
serves, from FastAPI and from django. it takes {} and answers a list, from every
project in the session, ordered by path and then by method, each
{
"framework": "fastapi",
"methods": ["GET"],
"path": "/v1/items/{item_id}",
"handler": {
"name": "app.items.read_item",
"uri": "file:///project/app/items.by",
"range": {"start": {"line": 6, "character": 0}, "end": {"line": 8, "character": 22}},
"selectionRange": {"start": {"line": 7, "character": 4}, "end": {"line": 7, "character": 13}}
},
"declaration": {
"uri": "file:///project/app/items.by",
"range": {"start": {"line": 6, "character": 1}, "end": {"line": 6, "character": 25}}
},
"application": {
"name": "app.main.app",
"uri": "file:///project/app/main.by",
"range": {"start": {"line": 4, "character": 0}, "end": {"line": 4, "character": 15}},
"selectionRange": {"start": {"line": 4, "character": 0}, "end": {"line": 4, "character": 3}}
}
}
framework is fastapi or django. methods are upper case, and empty for a
route that serves every method, as each of django's does. path is the whole
path, every prefix the route is mounted under included, with its parameters as
the route writes them, {item_id} or <int:pk>; a re_path() pattern is
joined to its prefixes with each part's ^ and $ anchors dropped. handler is
the function, or for a django view built by as_view() the class, with its
qualified name as name (absent where it has none, as application's may
be), its whole declaration as range and its name as
selectionRange; declaration is where the route is declared, the decorator
without its @, the add_api_route(...) or the path(...); application is the
FastAPI application that serves it, or the urlconf module django starts at, and
is absent for a route on a router no application includes. a route served under
two applications, or mounted twice, is listed once for each path.
every part is read through what the code means. a FastAPI route is a decorator,
or an add_api_route call, that resolves to a method of fastapi.FastAPI or
fastapi.APIRouter, get to trace for that method and api_route for its
methods= (GET without it), however the application or router is named or
imported; a router's routes are mounted by an include_router handed the same
router, under the include's prefix and the router's own APIRouter(prefix=),
through any number of routers between it and an application. a django route is
an entry of a urlconf module's urlpatterns that calls django.urls.path or
re_path, read from the module ROOT_URLCONF names, or, in a project whose
settings name none, from every module with urlpatterns that no other includes;
an include() is followed to the module a string names, a module object, a list
of patterns, or the patterns of a (patterns, app_name) pair. a path, a prefix
or a method that is not a string ty knows exactly — a literal, or a constant
holding one — leaves its route out rather than listing it at a path it may not
have, and so does a FastAPI router built somewhere other than where it is
assigned, and a route whose handler, declaration or application cannot be opened
merges and diffs¶
an editor's merge and diff tools compare versions of a file no document holds, so
these requests take texts, and an optional uri naming the file they are versions
of: its extension says how they are parsed (python without one), and the isort
configuration buff reads for it sorts imports (the first project's root's
without one).
by/resolveMergeConflicts takes the merge's three versions, base, ours and
theirs, each a whole file, and conflicts, the lines each conflict spans in
each version, {"base": {"start": 3, "end": 3}, "ours": {"start": 3, "end": 5}, "theirs": {"start": 3, "end": 4}}, 0-based with end excluded. it answers, for
each conflict in order, the text that replaces its lines, or null where it
cannot be resolved. a conflict is read as what its lines hold in each version's
whole syntax tree, and is resolved only where the lines are in the same body or
display in all three versions, and the two sides' changes provably touch nothing
in common:
- import statements: every import either side added, without those either side
removed, written as buff's isort configuration sorts and writes them. refused
when both sides changed what one name is bound to differently, when the result
binds one name to two things (
from a import xandfrom b import x), when a side imports a name the other side binds elsewhere other than by an import of the same thing, when either side has a star import among them, and when a comment is among them - functions and classes, methods among them, that each side added: each kept where it was added, at least two blank lines apart at the top level and one elsewhere. refused when a side changed or removed a statement or added anything else, or added a name the other side's version binds anywhere in that scope, in any form, or, in a class, assigns as an attribute anywhere in the file; a star import in that scope refuses too. what both sides added first or last in one place is kept once. definitions both sides added differently in one place are kept, ours first, only when running each binds its name and does nothing else: no decorator, no base class or class keyword, and every default and annotation a name or a literal
- elements of a list, set, tuple or dict display, or of a decorator list, that
each side added in a different place: each kept where it was added. refused
when both sides added different elements in one place, since a display
evaluates and keeps its elements in order and decorators apply in order, so
__all__entries both sides append are left to you, and when a side changed or removed one, two elements share a line, an element that would no longer be last has no comma after it, or both sides add one key of a dict - sides whose statements or elements are the same syntax tree with the same comments, which differ only in formatting: ours
anything else is null: lines that are not whole statements or whole elements,
and two sides that changed one statement, as LIMIT = 20 and LIMIT = 30 did.
by/reconcileMergeImports takes the merge's three versions, base, ours and
theirs, merged, the file the merge wrote, and markerSize, the size of the
conflict markers it may still have (7, as git writes them, without one; at least
1), and answers {"edits": [...], "choice": null}: the text edits to merged
that make its module-level imports say what its code reads. a line merge can be
clean and still break a file: ours removes the last function reading json and
import json with it, theirs adds another function reading json, and git
writes, without a conflict, a file that reads json and does not import it. the
versions' imports say where each name comes from, and the type checker says what
merged reads:
- a name
mergedreads where nothing binds it, resolved as go to definition resolves it where it is read, is imported as the versions import it, where ours and theirs between them import it from exactly one place, or, where neither does, the base does. a parameter of another function binds nothing where module code reads the name. nothing is added where no version imports it, or wheremergedhas a star import, which may bind it. a name__all__lists that the module does not bind counts as read - an import a side removed that nothing in
mergedreads, as the type checker'sunused-importdecides it, is removed: a mention in a docstring or a comment is not a read, and in a python file an annotation in quotes is. imports no side removed stay, re-exports and imports for their side effects among them - an added import goes where buff's isort configuration for the file sorts it, as
the editor's other quick fixes add theirs, in the file's line ending; a removed
one goes as
unused-import's fix removes it. no other line is written again, so imports a file keeps out of isort's order stay as they are
merged is read as a file of its project, so what its imports give it is what
the project gives it. where it still has conflicts, it is read as it would be
with each resolved to ours and with each resolved to theirs, so that whatever is
chosen has its imports, and only lines outside the conflicts are edited
where ours and theirs import a name merged needs from different places, or
merged's imports bind one name to two things where no version bound it to both,
nothing here can say which the code means: the answer has no edits and a choice,
{"name": "x", "imports": [{"version": "ours", "statements": [...]}, {"version": "base", ...}, {"version": "theirs", ...}], "position": {...}, "bindings": [...]}:
each version's import statements binding the name, as it writes them with any
comment on their line, where in merged the import belongs, and the ranges of the
lines of merged's import statements that bind that name and nothing else, which
whatever is chosen replaces. merged, or a version, that does not parse is
answered with no edits. by merge-driver
does the same for a merge git runs, where no merge window ever opens for a file
git merges cleanly
by/gitMergeIntegration takes {"uri"?: "…", "enable"?: true}, a file or
directory of the project asked about (the first project's without one), and
answers whether git merges it with by merge-driver,
{"enabled", "repository", "gitVersion", "gitSupported", "attributes", "missingAttributes", "driver", "driverFound", "driverCurrent"}:
whether every path the driver is for is merged by a driver that is there,
whether the project is in a git work tree, the version of the git on the language
server's PATH as git version writes it, whether that git is 2.44 or later, the
first that gives a merge driver what by merge-driver needs, the uri of its
.gitattributes, the patterns git does not merge with the driver, the command
merge.by.driver runs (null where it is not set), whether the by it names is
there, and whether the command is the one setting up writes, with its fallback to
git's own line merge, rather than one an older by wrote. with "enable": true
it first sets the integration up as
by init --git-merge does, the driver naming the
by the language server is, and fails for a project outside a git work tree, for
a git older than 2.44, and where its .gitattributes is there but cannot be read.
it answers null without a project
by/diffIgnoredRanges takes {"text": "…"} and answers what a diff ignoring
imports and formatting may ignore in it, {"imports": [...], "formatting": [...]},
each a list of ranges. imports is each import statement, wherever it is.
formatting is the text python's tokenizer discards without its being
significant: whitespace between two tokens of a logical line, the line breaks and
indentation of a line continued inside brackets or after a backslash, and blank
lines. the indentation a logical line starts with is not formatting, since it
says which block the line is in, and nor is anything inside an f-string or a
t-string, where f"{x = }" prints the spaces around its =. two texts that
differ only in what is ignored tokenize alike. a change that is formatting
across lines, as rewrapping a call is, is ignored only where each side's
whitespace is, which is as much as one text can say: whether two texts differ
only in formatting is a question about both, which by/resolveMergeConflicts
answers for a conflict
override and implement members¶
an editor's override methods and implement methods ask twice: once for what the class can override, to let its user pick, and once for the declarations of the ones picked. a code action cannot carry that, since its edit is worked out before anything is picked
by/overridableMembers takes a position in a class — its header, its body, or
an indented line below its last statement, where a new member would go — and
answers the class's name and the methods it inherits without defining them, in
MRO order of the superclass each comes from. each comes with that superclass and
its module, whether it is abstract where it is inherited from (what
abstract-instantiation counts as left unimplemented, so the ones implement
methods offers), whether it is a method, a classMethod or a staticMethod,
and its signature: the declaration that would be written, from its name on.
object's methods are listed, last; a final or private method, and the
constructors and the methods they call, are not. the answer is null where
there is no class, and for a file that is not basedpython
by/overrideMembers takes the same position and the names picked, and answers
the edits that write their declarations, in the order they were listed:
from pathlib import Path
class Square(Shape):
side = 1.0
override def area(self) -> float:
...
override def save(self, to: Path):
super.save(to)
each is declared override, with class, static, async or protected when
the method it overrides is — an async generator is not async, and returns the
generator its call makes — and with the signature the class inherits: a generic
superclass's type parameters filled in the way the class fills them, a method's
own type parameter renamed where it would hide one of the class's, an
overloaded method's overloads one declaration each. a type the file does not
reach yet is imported, and one it cannot name at all is left out, since a
parameter left unannotated takes the annotation of the one it overrides. a
default that is a value is left out of a method with a body for the same
reason, and one that is an expression is written as its base wrote it, with
each name in it imported, or written through its module where the file means
something else by it. the body
calls the method through super, or a static method, which has no super,
through its class's name; a method that is abstract has nothing to call, and
its body is ..., which the checker reports until it is written. -> None is
not written
the declarations go after the statement the position is in or follows, or at the
end of the body for a position in the header, and replace a body that is only
pass or .... the answer's selection is the first declaration's body as a
range in the text the edits leave behind, which is where the user goes next. it
is null when none of the names is a method the class could override
imports¶
an unresolved-reference is offered an import for every module with a member
of that name. when there is exactly one, its quick fix carries
{"unambiguousImport": true} in its data: nothing is left to choose, so an
editor may add it as the code is typed, the way IDEs add unambiguous imports on
the fly. isPreferred does not say this — every import that resolves a name is
preferred, since each properly fixes the diagnostic — and the mark changes
nothing for a client that does not read it
code copied from one module and pasted into another needs the imports it was
written against. by/copiedImports takes the copied text and the position in
the document it was copied from, one piece per caret, and answers each name the
text uses that the document's global scope binds there: name, the absolute
module, and the member imported from it, absent when the name is the module.
a name the text binds itself, a local of the scope it came from, and a builtin
are not answered. it takes the text rather than a range because a cut takes the
text out of the document, while the scope it was cut from still binds what its
names meant. by/pastedImports takes those imports, the document they were
pasted into and the range the paste now occupies, and answers the ones whose name
is not bound in the scope the paste landed in, with edits that add all of them.
a name bound there to something else is left alone, and so is an import of the
document's own module or of a module it cannot resolve. the edits of some of the
imports are not some of the edits — two imports from one module go into one
statement — so a client that lets its user choose asks again with the ones
chosen. both take textHash
unreachable code¶
code that can never run is reported as a hint: one diagnostic per range, with
severity 4 (hint), the tag 1 (Unnecessary) and the code
unreachable-code, for an editor to grey out or fade. the code tells the hint
apart from an unused name's, which has none; it names the hint and no rule. the
type checker does not report unreachable code, so no configuration selects it,
by/rules does not list it, by/explainRule answers null for it, and a
# ty: ignore[unreachable-code] comment names an unknown rule rather than
hiding it. its message is Code is always unreachable where no environment could
reach it — after a return, a raise, a continue, or a call that never
returns — and
Code is unreachable\nThis may depend on your current environment and settings
where the environment or the types decide it, such as a sys.version_info or
sys.platform branch, TYPE_CHECKING, or a condition a type rules out
a call that never returns ends the flow where it is made, inside a larger expression too. what the statement would have evaluated after it is reported as well, in as many ranges as it takes, several on one line:
a call whose arguments never finish being evaluated is never made, and its
callee is reported with its parentheses — print( in print(exit()),
obj.method( in obj.method(exit()) — when the callee only looks something
up: a name, an attribute of one, or one subscripted with a constant or a name,
handlers["k"](. python looks it up before the arguments, but the lookup is
reported as part of the call it names, which is never made. a callee that calls
or computes something of its own, f() in
f()(exit()) or xs[i()], did that, and is not reported, nor is an argument
evaluated before the one that never returns, a() in print(a(), exit()).
the other parts reported are the operation each enclosing expression would have
performed with the call's value and the operands it would have evaluated next —
+ and + b in x = a + exit() + b, and x =, since the store is never made —
the keyword of a return, a raise or a del, and the header of a for, a
with or a match around the call. each range is trimmed of the whitespace
around it, and parentheses written around an operand stay with the operand. an
operand that is not a callee is never reported, even a lookup: a in
a + exit() and d in d[exit()] are values the program already has, and a
decorator is not reported, since a def or a class is not read this way
a call counts only where the statement certainly makes it: not in the right
operand of and, or or ??, a branch of a conditional expression, a lambda's
body, anything of a comprehension but its first iterable, an optional chain past
its ?., an assert, or the test of an if or a while. a lambda's defaults
and the value of a cast count, since they are evaluated where they are
written. and a call inside a larger expression ends the flow only when its callee
says that it never returns — a function declared to return Never or whose body
never completes, or a value declared with a type whose call returns Never, as
the builtin exit is — not when a generic call's result is merely specialized to
Never
a module that does not transpile¶
a document's diagnostics include what stops it being transpiled, as the
diagnostic by build and by run stop on. a refusal is about how a module
lowers rather than what it means, so the check has nothing to say about it:
checks clean, and binds Optional, the name the runtime helper behind Some
is provided under. a star import binds what the module it imports exports, so
from typing import * is refused for the same module. the code is
transpile-refused for a module the transpiler
declines to lower, invalid-syntax for python it wrote that the target version
does not run, and internal-error for a transpiler that broke a contract of its
own. a failure about the python is put on the .by text it was copied from
where it was — the a of a case a: — and on the whole .by line it was
written for where the transpiler wrote it
it is asked only of a module the check reports no error in: the transpile of
one that does not check fails as often as not on what the check already
reported, and by run refuses such a module before it transpiles anything. a
transpile is answered once per change to the project, however often its
diagnostics are asked for. it is part of a document's diagnostics, pulled or
pushed, and not of the whole project's
what a module transpiles to¶
two requests answer about the python a .by module becomes, without a build:
| request | params | answers |
|---|---|---|
by/explainTranspilation |
textDocument |
each basedpython construct the document uses, and its lowering |
by/transpileForBuild |
textDocuments, buildDirectory |
the files' new slots in a running build's tree, or why not |
explaining a transpilation¶
by/explainTranspilation answers a list, in source order, of what the document
writes that python does not have, read off the tree the transpiler parses — so a
?. inside a string or a comment is not one, and a ? in a type is the optional
type rather than the operator:
[
{ "construct": "null-safe access", "snippet": "user?.email", "line": 4,
"explanation": "Lowered to a conditional that yields `None` when the receiver is `None`, and the attribute otherwise. A chain evaluates the receiver once." }
]
construct is a short name that stays the same from one release to the next:
pattern match, data-class modifier, null-coalescing operator,
force unwrap, propagate operator, optional type and null-safe access.
snippet is the source as written, line is one-based, and explanation is a
sentence for a reader. the answer is null for a document the server does not
hold
re-staging files into a running build¶
by run transpiles the project into a build tree and runs the program out of
it, so reloading an edit into the running program means putting new bytes in
that tree first. by/transpileForBuild computes them — for the files of an
edit, against the warm project the server already holds rather than a whole new
build — and writes nothing: the client writes them, so that it can roll the
write back together with whatever it does next if that is refused
its params are textDocuments, every document of the edit (their open buffers
are what is transpiled), and buildDirectory, the tree the program runs out of,
which only whatever started the program knows. the answer is one of two shapes:
{ "files": [ { "source": "/p/app/main.by", "generated": "/tmp/.tmpX/app/main.py",
"content": "…", "byDigest": "…", "pyDigest": "…", "changed": true } ],
"sourcemap": "…" }
each of files is one document's slot: where its bytes go, the whole text to
write there, the sha-256 of the source and of that text, and whether writing it
changes the tree. a file the build copied rather than transpiled is answered the
same way, with its bytes. sourcemap is the whole new _by_sourcemap.py, every
transpiled file's entry moved in it, or null when the map is unchanged. or:
every reason, one sentence each, about a file or, with file null, about the
tree: a tree built by another by or with --compiled, one with no sourcemap, a
file that is not one the build was made from, documents of different projects,
and a file that does not check, whose diagnostics come with it. a refusal is an
answer rather than an error, so that a client shows why the reload did nothing
the whole project's diagnostics¶
with diagnosticMode set to workspace, the server checks every file in the
project, open or not, and reports what it finds two ways:
| request | answers |
|---|---|
workspace/diagnostic |
once something differs from the result ids sent — held open until then |
by/checkWorkspace |
as soon as the check is done, whether or not anything differs |
both take the same parameters and report the same thing, file by file, with an
unchanged report for a file whose result id still matches. workspace/diagnostic
is the one an editor keeps a problems list current with: it asks again as soon
as it is answered, and the server answers when an edit or a change on disk
changes something. by/checkWorkspace is for a client that asks once — an
inspection over the whole project, a batch run with no editor — and would
otherwise wait forever on a project with nothing wrong in it. it is refused,
rather than answered empty, when the diagnostic mode does not check the
workspace
they differ in how the report arrives. workspace/diagnostic streams it as
partial results when the client sends a partialResultToken, and reports
progress under the client's workDoneToken. by/checkWorkspace ignores both
tokens: its report comes whole, in the response, and its progress, when the
client supports window/workDoneProgress, comes under a token the server
creates
by/checkWorkspace can take a while to answer, for two reasons:
- an edit or a change on disk that lands while the workspace is being checked starts the check again, on the changed workspace. the answer describes the workspace as it was when a check finished, and a workspace that never stops changing is never answered
- while a PEP 723 script's environment is being set up for the first time, the workspace is not checked, and the request waits until the environment is there. the first setup installs the script's dependencies, so it can take as long as that does
the program model¶
a run configuration, a test list and a "go to generated file" are all questions about the project rather than about a position in a file, and each used to be an editor's own guess at a layout the build decides. the server answers them instead, from the same reading the transpiler and the checker use:
| request | answers |
|---|---|
by/entryPoint |
whether a module has a main, and the command line the transpiler gives it |
by/testItems |
the tests pytest collects from a document, with their node ids |
by/runModules |
the modules by run can be given, and the one run.main names |
by/buildOutput |
where a project's build writes, and which output came from which source |
by/syntaxOutline |
a document's suites, clause keywords, declared names, lists and strings |
by/buildOutput maps both ways: given a .by it names the file the build writes
it to, given a file in the build directory it names the source. the path inside
the build follows the module tree, not the directory tree, so a src-layout
project's src/pkg/main.by is build/pkg/main.py — which is why this is the
build's answer rather than a path an editor can assemble
an editor that runs the build itself, for a build project action, takes the
build's diagnostics from its output rather than reading them as prose:
by build --output-format github, or TY_OUTPUT_FORMAT=github in the build's
environment as by check reads it, prints each diagnostic on a line of its own,
with its file, place and severity as named fields, among the lines saying what
the build wrote
by/syntaxOutline answers one document whole, on every revision the client wants
to serve features from: it is what an editor needs to type in an
indentation-delimited language — which line opens a suite, where a compound
statement ends, what a string literal's escapes and interpolations are, and how
much indentation a triple-quoted string has stripped. each string part also says
where its text is: the runs of the file whose text, joined, is what the literal
holds — one per line of a dedented string, past the indentation, and around the
interpolations of an f-string. that is what an editor needs to put another
language into a string it was not told about, with a place in the file for every
character of the fragment. the outline also carries the name each def and
class declares, a def's parameter names, and on a def a class body makes,
method: instance, class or static, what its first parameter is passed —
from @staticmethod and @classmethod, static def and class def, and the
methods python makes so by name, __new__ static (it is handed its class
explicitly, as its first argument) and __init_subclass__ and __class_getitem__
class methods; a plain function has none. beside it, receiver says what the
first parameter is, the self or cls an editor writes when the parameter
list is opened: instance or class, class for __new__ too, and absent for
any other static method.
a line broken inside an expression needs the expression in brackets, or a
backslash, to go on parsing. wrap names the expression Enter may break by
wrapping it in parentheses: on a simple statement, its one expression — an
assignment's value (=, an augmented one or an annotated one), a return's, an
expression statement, a raise with no from, an assert with no message, a
type alias's value; on a clause, its header's — the condition of if, elif
and while, the iterable of for, the subject of match. each of these means the
same in parentheses, so an editor breaking a line inside one, outside any bracket
already there, writes ( before the range and ) after it. a statement with two
expressions (raise E from cause, assert x, message) has none, and nor does an
expression whose parentheses are syntax or that is not one in python's sense — a
basedpython anonymous named tuple, a callable or protocol type, a statement used as
an expression, a starred expression. and it carries the elements of every
comma-separated list of two or more — what an editor moves an argument among, or
tracks a declaration being renamed by
.by test files are collected under the same names as python ones — test_*.by
and *_test.by — because a .by transpiles to the .py of the same stem, and
that is the file pytest sees
asking about the text you have¶
a client that keeps an answer against its own revision of a document can say
which text a document request is about, by adding textHash to the request's
params: FNV-1a, 64 bits, over the text's UTF-16 code units with every line ending
counted as one \n, written as sixteen lowercase hex digits. for a notebook cell
that is the cell's own text. the request is then answered about that text and no
other. when the server already holds it — the open buffer, or for
by/syntaxOutline, by/injections, by/superMembers,
by/documentSuperMembers, by/documentInheritedMembers,
by/documentUsageCounts, by/declaration, by/prepareMoveSymbol,
by/moveSymbol, by/testSubjects, by/subjectTests, by/transpile,
textDocument/semanticTokens/full and textDocument/documentSymbol the file on
disk of a document the client has not opened — it answers at once; otherwise the
request waits for the didOpen, didChange or file write that brings the text,
and is answered with ServerCancelled if nothing has after ten seconds. so a
client need not know whether its didOpen has gone out before it asks, and an
answer never describes text it did not ask about. a request without textHash is
answered as before, and refused for a document that is not open
debugger facts¶
while a program is stopped, an editor knows something no checker does: what the names in the current frame actually hold. the server takes those readings and answers what the code below the stop line will do, rather than what it could do
given a debugger stopped on line 5 holding limit = 5:
def compute() -> int: ...
limit = compute()
# stopped here
if limit > 100: # = false
over = 1 # will not run
nothing in the source decides that branch — compute() returns an int and any
int is possible. the reading of limit is what settles it
this is the checker's ordinary reachability analysis, reading the file under one extra assumption. it does not change the diagnostics you already see: a seeded reading and an unseeded one are separate questions, and the ordinary one is what the squiggles come from
the editor asks with a custom request, by/dataFlowAt:
{
"textDocument": { "uri": "file:///src/main.by" },
"line": 5,
"observations": [{ "name": "limit", "observed": "isInt", "text": "5" }]
}
line is one-based and is the line the program is stopped on. that line is
answered along with everything below it, because nothing on it has run yet.
a name may be a dotted path — self.limit — spelled as the source spells it
observed |
carries | means |
|---|---|---|
isNone |
the value is None |
|
isBool |
value |
exactly this bool |
isInt |
text, decimal |
exactly this integer |
isStr |
text |
exactly this string |
isBytes |
bytes, an array of numbers |
exactly these bytes |
isExactly |
module, qualname |
type(value) is this |
isEnumMember |
module, qualname, member |
this member of this enum |
the answer is a list of findings, each with a range, a kind of condition
or unreachable, a taken for a condition, and a label to draw
an empty answer is the ordinary case. only readings the server can express as a type produce anything, and only where nothing can have changed the name in between:
- a binding at or below the stop line is the program's own assignment, and wins over a reading taken before it
- a name a loop around the stop line rebinds is refused, because the reading is true of this iteration and not of the next
- an observation applies only to the scope the program is actually stopped in.
one frame's
limitis not another's, and a name that scope does not itself bind — a global it only reads, an attribute it never assigns — is a value nothing in that scope can vouch for
a value's type¶
a debugger names a value's type by its module and qualified name,
type(value).__module__ and __qualname__: shapes.base.Circle, or
shapes.base.Shape.Meta for a class nested in another. by/typeDeclaration
takes {"typeName": "shapes.base.Circle"} and answers the class that names, as
by/declaration describes a declaration — kind (always class), name, its
qualifiedName, and uri, range and selectionRange — for an editor's jump
to type source. the name is resolved as an import of it would be: its first part
as a module of the project's environment, and each part after it as a member of
what came before, through submodules and re-exports, so shapes.Circle, where
shapes/__init__ re-exports it, answers shapes.base.Circle. a class with a
source is answered at its source, and one with only a stub, as builtins.list,
at its stub, as is one whose module's source only imports it from where it is
implemented, as collections does deque from the C module _collections. the
answer is null for a name that reaches anything other than a
class, or nothing, as make.<locals>.Local does. a session of several projects
is answered from the first whose environment resolves it
the expression under the cursor¶
a debugger's value tooltip, and Evaluate Expression or Quick Evaluate with
nothing selected, start from the expression the cursor is on. which expression
that is depends on the code rather than the characters: on d in
a.b[c].d + compute(len(c)) it is a.b[c].d, on b it is a.b, and on c
it is c. the editor asks with by/evaluatableExpression:
{
"textDocument": { "uri": "file:///src/main.by" },
"position": { "line": 1, "character": 19 },
"calls": false
}
and the answer is the expression's range, or null where the position is not
on a name an expression ends with: a literal, an operator, a keyword, a comment,
or a name that a def, a class, an import or a keyword argument declares. a
parameter's name is the parameter. the program the debugger is stopped in is
python, so in a .by file an expression python would not read the same way,
like user?.name, is null too
calls says whether the expression may call anything, which is the difference
between hovering a name and asking for an evaluation. on compute the answer is
compute when it may not and compute(len(c)) when it may, and a reference
whose value comes out of a call, like make().d, is answered only when it may.
reading an attribute or an item is answered either way, as every python
debugger's value tooltip does
renaming what goes with a symbol¶
a rename (textDocument/rename) renames a symbol's declaration and every use of
it. beside that, as PyCharm does for a .py rename, it offers the renames that
usually go with it, for the user to choose:
| label | offered when renaming | renames |
|---|---|---|
Rename overriding methods |
a method | each method that overrides it, and its uses, so it keeps overriding |
Rename parameters of overriding methods |
a parameter of a method | the parameter of that name in each overriding method, keyword arguments too |
Rename module |
a module's class | the module the class names, animal.by for Animal, and the imports of it |
a module is named after a class when its file's name is the class's but for case; the new file is named the same way and put beside the old one, and none is offered when a file of that name is there already
they are offered only to a client that says it takes them: one whose
workspace.workspaceEdit capability has documentChanges: true and a
changeAnnotationSupport. its rename is answered as documentChanges, a
TextDocumentEdit per file followed by a RenameFile for a module, which is
sent only when resourceOperations includes rename. the rename itself is
plain text edits, and each offered rename is a change annotation with
needsConfirmation: true, which its text edits — and its RenameFile — carry:
{
"documentChanges": [
{ "textDocument": { "uri": "file:///p/dog.by", "version": null },
"edits": [
{ "range": { "start": { "line": 10, "character": 12 }, "end": { "line": 10, "character": 17 } },
"newText": "talk" },
{ "range": { "start": { "line": 4, "character": 17 }, "end": { "line": 4, "character": 22 } },
"newText": "talk", "annotationId": "override:0" } ] }
],
"changeAnnotations": {
"override:0": { "label": "Rename overriding methods",
"description": "`dog.Dog.speak`", "needsConfirmation": true }
}
}
the identifiers are override:<n>, parameter:<n> and module:<n>, numbered
from 0 within each kind. the label is the kind, shared by every offer of it, so a
client that groups on labels shows one group per kind, and the description names
what one offer renames. a client applies the edits of the offers the user keeps
and leaves out the others; none of them touches an occurrence the rename itself
makes. a client without the capability gets the rename alone, as plain changes,
as before
the offers as edits of their own¶
a client that cannot read change annotations — one whose protocol library takes an annotated text edit for a plain one, as lsp4j does — asks for the offers on their own, with the rename's own params:
| request | params | answers |
|---|---|---|
by/renameOffers |
textDocument, position, newName |
[{ "id", "label", "description", "edit" }] |
each offer is the one the annotated rename gives, with the same id, label
and description, and edit is a workspace edit of its own that makes it and
nothing else: plain changes, or for a module, documentChanges holding a
TextDocumentEdit per file and then the RenameFile, without annotations. the
rename itself is still textDocument/rename's, asked of a client that leaves
out changeAnnotationSupport so that it is answered alone. a new name the
rename would refuse is refused with the same reason, and there is nothing to
offer, [], where there is no python symbol to rename. both answers are made by
the same code, so they offer the same
every position in an offer's edit is one in the text before the rename, as the
rename's own edits are. so the edits of the rename and of the offers the user
keeps are one edit, to be merged and applied together. applied one after another
they would land in the wrong place wherever an earlier one changed the length of
a line, as the two speaks of print(a.speak(), d.speak()) do when only a's
is the rename's
a rename's new name¶
an editor that asks for a new name can check it, and offer some, before the rename is asked for:
| request | params | answers |
|---|---|---|
by/validateRenameName |
textDocument, position, newName |
{ "valid": true }, or { "valid": false, "message" } |
by/renameNameSuggestions |
textDocument, position |
names the symbol could take, best first |
by/validateRenameName judges the name by the rule textDocument/rename refuses
it by, and gives the reason the rename would: a python symbol's new name is an
identifier that is not a keyword (`class` is a keyword), while a django
name is held to what django's own rename takes, which depends on the kind of
name it is. a symbol that cannot be renamed at all, such as a builtin, is
valid: false with the reason, whatever the name; where there is nothing to
rename the answer is null, as textDocument/prepareRename's is
by/renameNameSuggestions names a symbol after what it holds: the class of its
value, as http_request and request for an HttpRequest, in the plural for a
list, set, frozenset or tuple of one (users), but not after a class of
builtins or types, which says what kind of value it is rather than what it
is for; and what its
value is computed by, as extracting a variable does, user for get_user().
every suggestion is a name the rename takes, none is a word basedpython reads as
a keyword, and none is the name the symbol has
renaming a module¶
renaming util.by to helpers.by renames the module alpha.util, and every
from alpha.util import thing in the project now names a module that is not
there. an editor cannot find those on its own — it would have to resolve every
import against the same search paths the checker uses — so it asks first
the request is the protocol's own workspace/willRenameFiles, sent before the
file moves, and the answer is the edits that keep the project working. the
ordering is what makes the answer computable: the old path still holds the file,
so the module it is today can be resolved, and the new path is a path to read a
name out of
both a file and a directory are asked about, because renaming a directory renames every module under it — the client sends only the directory, never its contents
what gets rewritten:
import alpha.util # the dotted name
import alpha.util as util # ... with an alias, which is left alone
from alpha.util import thing # the module a symbol comes from
from alpha import util # the module imported as a name
from .util import thing # a relative import, after the dots
and the uses of a name an import binds, when that name changes.
import alpha.util binds alpha, so alpha.util.thing() in the body is part of
the rename too. those are found by asking what each expression is rather than by
matching text — a local called util in a file that also imports a module of
that name is not a reference to the module, and is not touched
a relative import inside a package that is being renamed as a whole comes out
unchanged, which is the truth: nothing about from .util import thing stops
working because its package was renamed around it
two things are deliberately not rewritten:
- a module named as a string —
importlib.import_module("alpha.util"), anINSTALLED_APPSentry, an entry point inpyproject.toml. django's own module strings are handled by the django rename, and the rest are not distinguishable from any other string - an import that would have to change shape — moving
alpha.utiltobeta.utilleavesfrom alpha import utilneeding a different statement, not a different word. those are reported in the server log rather than rewritten into something that does not mean the same thing