Import Surface and Declarations

The canonical import block, all importable names, and the indicator / strategy / library declaration functions.

Import Surface#

from source import (
    strategy,
    indicator,
    library,
    input,
    ta,
    request,
    array,
    barstate,
    log,
    plot,
    plotbar,
    plotcandle,
    plotshape,
    plotchar,
    plotarrow,
    barcolor,
    fill,
    bgcolor,
    hline,
    line,
    label,
    box,
    polyline,
    linefill,
    table,
    gfx,
    atk,
    chart,
    na,
    nz,
    var,
    varip,
    set_var,
    alert,
    alertcondition,
    library_import,
    import_library,
)

Enums#

Optional enums available for explicit import: Location, Position, Shape, Size, Weight.

Advanced helpers#

get_pynescript_module_metadata(module), build_pynescript_visual_snapshot(...), compile_pynescript_module_classes(module).

Script identity#

Always set # @name: my_script or __script_name__ = "my_script" so publish/update identity is stable.

indicator, strategy, library#

`indicator(title: str, **kwargs) -> dict`#

Registers indicator metadata into module context and controls whether the compiled wrapper becomes a main-chart overlay or a sub-panel indicator.

ATK behavior: overlay=True compiles to BaseIndicator. overlay=False compiles to BaseSubIndicator.

Important kwargs: overlay, shorttitle, precision, timeframe, description, default_styles, behind_chart, explicit_plot_zorder, scale, max_lines_count, max_boxes_count, max_labels_count, max_polylines_count, max_bars_back.

`strategy(title: str, **kwargs) -> dict`#

Registers strategy metadata and preserves execution-related flags for diagnostics and runtime behavior.

Current note: process_orders_on_close has the strongest practical runtime behavior today. Tick-level semantics remain partial.

Important kwargs: overlay, shorttitle, precision, calc_on_every_tick, calc_on_order_fills, process_orders_on_close, fill_orders_on_standard_ohlc, max_bars_back, timeframe, description, default_styles.

`library(title: str, **kwargs) -> dict`#

Registers a publishable declaration library whose exported functions are discovered from module callables defined in the same file. Libraries can later be loaded with library_import(...) or import_library(...).

Useful kwargs: version, overlay, description.

How to choose#

Use indicator(...) when the script's primary output is visual analysis. If the script does not emit mapped trade fields, keep it as an indicator even if it contains buy/sell hints.
Use strategy(...) when the script should produce mapped entry and risk fields that the ATK execution pipeline can consume.
Use library(...) when you want reusable calculation helpers, validation helpers, or shared signal logic that multiple scripts import.

Declaration parameter reference#

Parameter	Where it matters	How to choose it
`title`	User-facing script identity	Pick the readable name users should see in menus and script lists. Keep it stable once published.
`overlay`	Panel placement	`True` for price chart visuals. `False` for oscillators and sub-panel indicators.
`shorttitle`	Tight UI surfaces	Use when the full title is long. Keep it recognizable.
`precision`	Displayed number formatting	Match the unit users care about. Four decimals for FX/crypto; zero or two for counts or dashboard summaries.
`timeframe`	Declaration metadata	Only set when intentionally tied to a specific higher timeframe. Leave unset if the script should adapt to the active chart.
`description`	Publish and maintenance clarity	One sentence explaining what the script computes and what the user expects to see.
`default_styles`	Initial visual appearance	Use for predictable starting style on multi-plot scripts. Keep style changes cosmetic.
`behind_chart`	Overlay layering	Use for background-like visuals such as zones and shading.
`explicit_plot_zorder`	Overlay plot ordering	Enable when line ordering matters — upper/lower bands, stacked fills.
`max_*_count`	Object-heavy scripts	Increase only when the script genuinely creates many lines, labels, boxes, or polylines.
`max_bars_back`	Warmup depth	Set to at least the longest lookback the script needs, plus safety margin.
`process_orders_on_close`	Strategy execution timing	Use for bar-close strategies where signals convert into orders after bar completes.
`calc_on_every_tick`	Strategy intent metadata	Treat as advanced metadata; do not use as a shortcut for fixing bar-close logic.

Authoring rule: choose the declaration by runtime responsibility, not by visual appearance. A script that draws arrows is still an indicator if it does not emit mapped trade fields.

Indicator declaration example#

from source import indicator, input, ta, plot

indicator(
    "EMA Overlay",
    overlay=True,
    precision=4,
    explicit_plot_zorder=True,
    max_lines_count=5,
)
length = input.int(21, title="Length", key="length", minval=1)
plot("ema", key="ema_line", title="EMA", color="#00c853", width=2)


def build_indicator_frame(df, params):
    frame = df.copy().reset_index(drop=True)
    frame["ema"] = ta.ema(frame["close"], int(params.get("length", length)))
    return frame

Strategy and library declarations#

from source import build_mapped_trade_frame, import_library, input, strategy


# strategy(...) is chosen because this script will emit canonical trade-frame execution fields.
strategy("EMA Cross Strategy", overlay=True, process_orders_on_close=True, max_bars_back=240)
fast_period = input.int(10, title="Fast EMA", key="fast_period", minval=1)
slow_period = input.int(24, title="Slow EMA", key="slow_period", minval=2)


# import_library(...) is used only when logic should be reused across scripts.
shared = import_library("Annotated Utility Library@1", exports=["clamp_length"])
safe_fast = shared.clamp_length(fast_period, 1)


def build_signal_frame(df, params=None):
    ...


def build_trade_frame(signal_df, params=None, styles=None):
    return build_mapped_trade_frame(signal_df)

Processing Flows

input.*