Linting¶
Hooks are matched to their state by call order, so a hook that runs on
one render and not the next corrupts every hook after it. A stale
dependency list is quieter: the effect keeps using the values from the
render that created it. pn lint catches both before you run the app.
It's the PythonNative counterpart of eslint-plugin-react-hooks. It
also checks worklets, the functions that run on
the UI thread, so a construct the core can't run shows up in your
editor instead of on a device.
The linter reads your source with Python's ast module. It never
imports or runs your code, and it has no dependencies beyond
PythonNative itself.
Running it¶
pn lint # lints app/ (or the current directory if there's no app/)
pn lint app tests # lints specific files and directories
pn lint --json # prints a JSON array for editors and CI
Each finding prints as path:line:col: CODE message:
app/main.py:14:9: PN101 hook 'use_state' is called inside an 'if' statement; call hooks unconditionally at the top level of 'Profile'
app/main.py:22:43: PN103 use_effect callback reads 'user_id' but it is missing from the dependency list
Found 2 problems.
pn lint exits 1 when it finds anything and 0 when it doesn't, so it
works as a CI gate as is. It exits 2 when a path you named doesn't
exist.
With --json, stdout carries only the array, one object per finding
with path, line, col, code, and message keys, and the summary
line goes to stderr.
Directories are searched recursively for *.py files. The linter skips
.git, build, dist, .venv*, __pycache__, node_modules, and
site. A file you name directly is linted whatever its extension.
What counts as a hook, a component, and a custom hook¶
- A hook is any call whose final name is
use_followed by a lowercase letter:pn.use_state(...),use_effect(...),hooks.use_ref(...), or your ownuse_cart(). Leading underscores are allowed, so private helpers like_use_navigator()count too. - A component is a function decorated with
@component,@pn.component, or@pythonnative.component, including when it's stacked under@pn.memo. A function passed straight topn.component(fn)orComponent(fn, ...)in the same file counts too. - A custom hook is a function whose name is a hook name, such as
def use_cart():.
Components and custom hooks are the only places a hook may run.
Rules¶
PN101: hooks must run unconditionally¶
A hook call inside a component or custom hook must run on every render,
in the same order. PN101 flags a hook inside any of these:
- an
if,elif, orelseblock - a
fororwhileloop - a
trystatement, including itsexcept,else, andfinallyblocks - a
matchstatement - a comprehension or generator expression
- a lambda
- either branch of a conditional expression (
a if cond else b) - the right side of
andoror - a function or class defined inside the component
- any statement after an early
return
@pn.component
def Profile(user_id: int | None) -> pn.Node:
if user_id is None:
return pn.Text("Signed out")
user, set_user = pn.use_state(None) # PN101: after an early return
return pn.Text(f"User {user_id}")
Move the condition inside the hook, or call the hook first and branch afterward:
@pn.component
def Profile(user_id: int | None) -> pn.Node:
user, set_user = pn.use_state(None)
if user_id is None:
return pn.Text("Signed out")
return pn.Text(f"User {user_id}")
Positions that always run are fine: the test of an if, the iterable
of a for loop, a with statement and its body, the first operand of
and or or, and the first iterable of a comprehension.
PN102: hooks only run in components and custom hooks¶
PN102 flags a hook called at module level, in a plain function, or in
a method:
theme = pn.use_theme() # PN102: at module level
def header():
count, _ = pn.use_state(0) # PN102: 'header' isn't a component
return pn.Text(str(count))
Decorate the function with @pn.component, or rename it use_* if
it's meant to be a custom hook. A hook inside a function nested in a
component, such as an event handler, is PN101 instead, because the
handler doesn't run during render.
PN103: dependency lists must be complete¶
For use_effect, use_layout_effect, use_memo, use_callback, and
use_focus_effect, PN103 compares the names the callback reads with
the dependency list. It only checks a call when the list is a literal
list or tuple and the callback is a lambda or the name of a function
defined in the same component or custom hook.
@pn.component
def Profile(user_id: int) -> pn.Node:
user, set_user = pn.use_state(None)
async def load():
set_user(await fetch_user(user_id))
pn.use_effect(load, []) # PN103: reads 'user_id'
...
With [], the effect loads the first user forever. List every
component-scoped name the callback reads, here [user_id].
A name only needs to be listed when the component or custom hook binds it: a parameter, a local assignment (including tuple unpacking), or a nested function. These are exempt:
- names defined at module level, and builtins
- the setter from
value, set_value = pn.use_state(...)and the dispatcher fromstate, dispatch = pn.use_reducer(...) - names assigned from
pn.use_ref(...)orpn.use_shared_value(...) - names assigned from
pn.use_memo(...)orpn.use_callback(...)with a literal empty dependency list, which are computed once - names bound by an import inside the component
The state value itself isn't exempt, and a setter or ref stops being exempt if the name is assigned again somewhere else in the component.
Reading an attribute counts as reading its root name, so
props.title needs props in the list. Listing props.title also
satisfies it: a dependency covers every name it mentions.
PN103 doesn't check a call whose dependency list is omitted, None,
or built at runtime (deps, list(xs)), and it skips callbacks it
can't see into, such as make_handler(x).
The finding is reported on the line of the dependency list.
PN104: user components take keys through .with_key()¶
User components don't accept key=: the parameters come from your
function's signature, so there's nowhere for the key to go. PN104
flags key= in a call to a module-level @component defined in the
same file:
@pn.component
def Row(item: Item) -> pn.Node:
return pn.Text(item.title)
pn.Column(*[Row(item, key=item.id) for item in items]) # PN104
Key the element instead:
Built-in elements like pn.View(key=...) are fine. A component
can't declare a parameter named key at all: @pn.component raises
TypeError for one, and calling a component with key= raises
TypeError at run time too.
PN105: components don't change module-level state while rendering¶
A component's body should only compute what to show. A render can run
more than once for one update (a transition that's interrupted starts
over, for example), so a change it makes to state outside the component
happens more than once. PN105 flags, directly in a component's body:
- assigning a module-level name declared
global, including augmented assignment (global count; count += 1) - assigning or deleting an item of a module-level name
(
CACHE[key] = value,del CACHE[key],CACHE[key] += 1) - calling a method that changes a list, dict, set, or deque in place on
a module-level name (
SEEN.append(x),CACHE.update(...),CACHE.pop(key),TAGS.add(tag))
_seen: list[str] = []
@pn.component
def Row(item: Item) -> pn.Node:
_seen.append(item.id) # PN105
return pn.Text(item.title)
Keep the value in state or a ref, or make the change in an effect or an event handler. Nested functions, lambdas, and classes aren't checked, since they run later, and neither is a name the component binds itself, such as a parameter or a local copy.
PN201: worklets must compile¶
Every function marked @pn.worklet, and every inline lambda passed to
a worklet-only API or to on_finish=, entering=, exiting=, or
layout=, is compiled the way the renderer core will compile it.
PN201 reports a construct outside the
worklet subset, with the compiler's message,
at the construct's position:
@pn.worklet
def settle(event: gestures.GestureEvent) -> None:
while offset.value > 0: # PN201: `while` loops can't run on the UI thread; use `for i in range(n)`
offset.value -= 1
These are the same errors a release build reports when it precompiles
worklets, so a clean pn lint means pn build won't stop on one.
Errors that depend on what a worklet captures at run time, such as
calling a plain Python function, are reported when the worklet is
installed instead; see Errors.
PN202: worklet-only APIs need a marked worklet¶
use_animated_style, use_derived_value, use_animated_reaction, and
use_frame_callback only accept a @pn.worklet function or an inline
lambda. PN202 flags a name passed to one of them that isn't decorated
in the same file:
@pn.component
def Card() -> pn.Node:
offset = pn.use_shared_value(0.0)
def fade() -> pn.Style:
return {"opacity": offset.value}
style = pn.use_animated_style(fade) # PN202: mark 'fade' with @pn.worklet
...
The hook raises TypeError for it at run time too. Requiring the
marker keeps code that would compile in development, where every
function has its source, from failing in a release build, which only
precompiles marked worklets and inline lambdas. Add @pn.worklet, or
pass a lambda.
PN203: shared values aren't read during render¶
PN203 flags a read of .value on a shared value (a name assigned
from pn.use_shared_value(...) or pn.use_derived_value(...)) in a
component's body:
@pn.component
def Progress() -> pn.Node:
progress = pn.use_shared_value(0.0)
label = f"{progress.value:.0%}" # PN203: won't rerun when it changes
...
The read works, but it returns the value at the moment of the render,
and the component doesn't render again when the value changes. Read it
in a worklet, such as a use_animated_style or use_derived_value
lambda, or keep the number in state if text has to show it. Reads
inside nested functions and lambdas aren't flagged, since those run
later.
PN000: the file couldn't be read¶
A file with a syntax error, or one that isn't valid UTF-8, produces a
single PN000 finding. The linter doesn't check the rest of it.
Suppressing a finding¶
Add a # pn: ignore comment to the line the finding is reported on.
Name the codes in brackets to silence only those:
config = pn.use_memo(build_config, []) # pn: ignore[PN103]
pn.use_effect(lambda: x, []) # pn: ignore[PN101,PN103]
legacy = pn.use_state(0) # pn: ignore
Prefer the bracketed form so that a new problem on the same line still
shows up. PN000 can't be suppressed.
Limits¶
The linter works on one file at a time and doesn't infer types, so:
- It recognizes components by their decorator and hooks by their name.
A component created some other way, or a hook imported under an
alias that doesn't start with
use_, isn't recognized. PN104only knows about components defined at module level in the same file.PN105only sees names assigned at module level in the same file, and it goes by method name: callingaddorupdateon any such name is flagged, and mutating an imported object isn't.PN202only knows about worklets decorated in the same file. A worklet imported from another module is flagged; suppress the finding on that line.PN103treats every local value as changing between renders. A value that you know is stable, such as ause_memo(..., [])result, still has to be listed or suppressed.- It doesn't follow control flow: a hook after
if not ok: raise ValueError(...)is fine, but one afterif not ok: return Noneis flagged.