pine2pyne 0.2.4__py3-none-any.whl

pine2pyne/emit/pynecomp/passes/hoisting.py

@@ -0,0 +1,205 @@
+"""Temporaries PyneComp hoists in front of a statement (Pine v4/v5).
+
+Pine v4 and v5 evaluate both operands of ``and``/``or``; Python evaluates the
+second only when needed. PyneComp keeps a stateful call (``ta.*``,
+``request.*``, a user function) in the second or a later operand running on
+every bar by computing it first, into ``<name>_<n>``; a time function given a
+time (``month(time)``) counts as stateful, and a stateful call in the arguments
+of one is computed before it::
+
+    crossover_1 = ta.crossover(close, fastSma)
+    long = fastAboveSlow and crossover_1
+
+The number counts per name within one block. Pine v4 ``iff(c, a, b)`` is
+``a if c else b``; an ``iff`` nested in its arguments is hoisted the same way
+(``iff_1 = ...``), innermost first, after the calls.
+"""
+from __future__ import annotations
+
+import ast
+from typing import Callable
+
+from .base import PassContext
+
+_BLOCK_FIELDS = ('body', 'orelse', 'finalbody')
+#: the time functions PyneComp hoists like a stateful call when they are given a time
+TIME_FUNCTIONS = frozenset({'time', 'time_close', 'year', 'month', 'weekofyear', 'dayofmonth', 'dayofweek',
+                            'hour', 'minute', 'second'})
+
+
+def _call_name(call: ast.Call) -> str | None:
+    func = call.func
+    if isinstance(func, ast.Name):
+        return func.id
+    if isinstance(func, ast.Attribute):
+        return func.attr
+    return None
+
+
+def _dotted(node: ast.expr) -> str:
+    if isinstance(node, ast.Attribute):
+        return f'{_dotted(node.value)}.{node.attr}'
+    return node.id if isinstance(node, ast.Name) else ''
+
+
+class _BlockNames:
+    """``<name>_<n>`` numbering within one block."""
+
+    def __init__(self) -> None:
+        self._counts: dict[str, int] = {}
+
+    def next(self, stem: str) -> str:
+        self._counts[stem] = self._counts.get(stem, 0) + 1
+        return f'{stem}_{self._counts[stem]}'
+
+
+def _statement_expressions(statement: ast.stmt) -> list[tuple[ast.AST, str]]:
+    """(owner, field) of the expressions a statement evaluates before its body runs;
+    an `elif` condition belongs to its `if`."""
+    if isinstance(statement, ast.If):
+        found = [(statement, 'test')]
+        orelse = statement.orelse
+        while len(orelse) == 1 and isinstance(orelse[0], ast.If):
+            found.append((orelse[0], 'test'))
+            orelse = orelse[0].orelse
+        return found
+    if isinstance(statement, (ast.Assign, ast.AnnAssign, ast.AugAssign, ast.Expr, ast.Return)):
+        return [(statement, 'value')] if getattr(statement, 'value', None) is not None else []
+    if isinstance(statement, ast.For):
+        return [(statement, 'iter')]
+    return []
+
+
+def _nested_blocks(statement: ast.stmt):
+    """The blocks a statement holds, elif chains included."""
+    for field in _BLOCK_FIELDS:
+        block = getattr(statement, field, None)
+        if isinstance(block, list) and block:
+            if isinstance(statement, ast.If) and field == 'orelse' and len(block) == 1 and isinstance(block[0], ast.If):
+                yield from _nested_blocks(block[0])
+                yield block[0].body  # the elif's own body
+                continue
+            yield block
+
+
+def rewrite_blocks(tree: ast.Module, rewrite: Callable[[ast.stmt, _BlockNames], list[ast.stmt]]) -> None:
+    """Apply ``rewrite`` (statement -> statements to insert before it) to every block."""
+    def visit(block: list[ast.stmt]) -> None:
+        names = _BlockNames()
+        index = 0
+        while index < len(block):
+            statement = block[index]
+            inserted = rewrite(statement, names)
+            for offset, new in enumerate(inserted):
+                block.insert(index + offset, ast.copy_location(new, statement))
+            index += len(inserted)
+            if not isinstance(statement, (ast.FunctionDef, ast.ClassDef)):  # functions: visited on their own
+                for nested in list(_nested_blocks(statement)):
+                    visit(nested)
+            index += 1
+    for node in ast.walk(tree):
+        if isinstance(node, ast.FunctionDef):
+            visit(node.body)
+
+
+class StrictBooleanHoistingPass:
+    """Pine v4/v5: stateful calls in a later operand of ``and``/``or`` are computed first."""
+
+    def apply(self, tree: ast.Module, context: PassContext) -> None:
+        if context.pine_version >= 6:
+            return
+        user_functions = {node.name for node in ast.walk(tree) if isinstance(node, ast.FunctionDef)}
+
+        def stateful(call: ast.Call) -> bool:
+            dotted = _dotted(call.func)
+            if dotted in TIME_FUNCTIONS:
+                return bool(call.args or call.keywords)  # `month(time)`, `hour(time, tz)` (corpus)
+            return (dotted.startswith(('ta.', 'request.')) or dotted in user_functions) and dotted != 'main'
+
+        def rewrite(statement: ast.stmt, names: _BlockNames) -> list[ast.stmt]:
+            hoisted: list[ast.stmt] = []
+
+            def hoist_in(node: ast.AST) -> ast.AST:
+                """``node`` with its outermost stateful calls replaced by temporaries."""
+                if isinstance(node, ast.Call) and stateful(node):
+                    # a stateful call in its arguments first: `ema_1 = ta.ema(close, 5)`, `change_1 = ta.change(ema_1)`
+                    for index, argument in enumerate(node.args):
+                        node.args[index] = visit_operand_free(argument, hoist=True)
+                    for keyword in node.keywords:
+                        keyword.value = visit_operand_free(keyword.value, hoist=True)
+                    name = names.next(_call_name(node))
+                    hoisted.append(ast.Assign(targets=[ast.Name(id=name, ctx=ast.Store())], value=node))
+                    return ast.Name(id=name, ctx=ast.Load())
+                return visit_operand_free(node, hoist=True)
+
+            def visit_operand_free(node: ast.AST, hoist: bool = False) -> ast.AST:
+                """Walk ``node``; BoolOps inside it hoist from their later operands."""
+                if hoist and isinstance(node, ast.Call) and _dotted(node.func) == 'inline_series' \
+                        and len(node.args) == 2 and isinstance(node.args[0], ast.Call) and stateful(node.args[0]):
+                    # `inline_series(ta.lowest(l, n), n)`: the call is hoisted as a series and read with history,
+                    # `lowest_1: Series = ta.lowest(l, n)`, `lowest_1[n]` (MightyZinger/Chikou)
+                    temporary = hoist_in(node.args[0])
+                    hoisted[-1] = ast.AnnAssign(target=ast.Name(id=temporary.id, ctx=ast.Store()),
+                                                annotation=ast.Name(id='Series', ctx=ast.Load()),
+                                                value=hoisted[-1].value, simple=1)
+                    return ast.Subscript(value=temporary, slice=visit_operand_free(node.args[1]), ctx=ast.Load())
+                if isinstance(node, ast.BoolOp):
+                    node.values[0] = visit_operand_free(node.values[0])
+                    node.values[1:] = [hoist_in(value) for value in node.values[1:]]
+                    return node
+                if hoist and isinstance(node, ast.Call) and stateful(node):
+                    return hoist_in(node)
+                for field, value in ast.iter_fields(node):
+                    if isinstance(value, ast.AST) and not isinstance(value, (ast.expr_context, ast.operator)):
+                        setattr(node, field, visit_operand_free(value, hoist))
+                    elif isinstance(value, list):
+                        setattr(node, field, [visit_operand_free(item, hoist) if isinstance(item, ast.AST) else item
+                                              for item in value])
+                return node
+
+            for owner, field in _statement_expressions(statement):
+                setattr(owner, field, visit_operand_free(getattr(owner, field)))
+            return hoisted
+
+        rewrite_blocks(tree, rewrite)
+
+
+class LegacyIffPass:
+    """Pine v4 ``iff(c, a, b)`` is ``a if c else b``; a nested ``iff`` is hoisted to ``iff_<n>``."""
+
+    def apply(self, tree: ast.Module, context: PassContext) -> None:
+        if context.pine_version >= 5:
+            return
+
+        def is_iff(node: ast.AST) -> bool:
+            return (isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id == 'iff'
+                    and len(node.args) == 3 and not node.keywords)
+
+        def rewrite(statement: ast.stmt, names: _BlockNames) -> list[ast.stmt]:
+            hoisted: list[ast.stmt] = []
+
+            def ternary(call: ast.Call, nested: bool) -> ast.expr:
+                condition, then, otherwise = (convert(argument, nested=True) for argument in call.args)
+                expression = ast.IfExp(test=condition, body=then, orelse=otherwise)
+                if not nested:
+                    return expression
+                name = names.next('iff')
+                hoisted.append(ast.Assign(targets=[ast.Name(id=name, ctx=ast.Store())], value=expression))
+                return ast.Name(id=name, ctx=ast.Load())
+
+            def convert(node: ast.AST, nested: bool = False) -> ast.AST:
+                if is_iff(node):
+                    return ternary(node, nested)
+                for field, value in ast.iter_fields(node):
+                    if isinstance(value, ast.AST):
+                        setattr(node, field, convert(value, nested))
+                    elif isinstance(value, list):
+                        setattr(node, field, [convert(item, nested) if isinstance(item, ast.AST) else item
+                                              for item in value])
+                return node
+
+            for owner, field in _statement_expressions(statement):
+                setattr(owner, field, convert(getattr(owner, field)))
+            return hoisted
+
+        rewrite_blocks(tree, rewrite)

pine2pyne/emit/pynecomp/passes/imports.py

@@ -0,0 +1,112 @@
+"""Imports that match what the rewritten module actually uses."""
+from __future__ import annotations
+
+import ast
+import builtins
+
+from .base import PassContext
+
+#: Where PyneComp imports a name from, for the names that do not live in
+#: ``pynecore.lib`` (mined from the import blocks of ``assets/pyne``)
+KNOWN_ORIGINS: dict[str, str] = {
+    'pine_range': 'pynecore', 'pine_loop': 'pynecore',
+    'overload': 'pynecore.core.overload',
+    'cast_bool': 'pynecore.core.pine_cast', 'cast_int': 'pynecore.core.pine_cast',
+    'cast_float': 'pynecore.core.pine_cast', 'cast_string': 'pynecore.core.pine_cast',
+    'Exported': 'pynecore.core.pine_export', 'export': 'pynecore.core.pine_export',
+    'shadowed_namespace': 'pynecore.core.pine_import',
+    'method_call': 'pynecore.core.pine_method', 'method': 'pynecore.core.pine_method',
+    'udt': 'pynecore.core.pine_udt', 'udt_copy': 'pynecore.core.pine_udt',
+    'inline_series': 'pynecore.core.series',
+    'Color': 'pynecore.types', 'Line': 'pynecore.types', 'NA': 'pynecore.types',
+    'Persistent': 'pynecore.types', 'PersistentSeries': 'pynecore.types', 'Series': 'pynecore.types',
+    'Box': 'pynecore.types', 'Label': 'pynecore.types', 'Table': 'pynecore.types',
+    'IBPersistent': 'pynecore.types', 'IBPersistentSeries': 'pynecore.types', 'LineFill': 'pynecore.types',
+    'Matrix': 'pynecore.types', 'Polyline': 'pynecore.types', 'Footprint': 'pynecore.types',
+    'ChartPoint': 'pynecore.types.chart',
+    'field': 'dataclasses', 'StrEnum': 'enum',
+}
+
+#: Names PyneComp imports from ``pynecore.lib`` (the same mining)
+LIB_NAMES = frozenset((
+    'adjustment alert alertcondition array ask bar_index barcolor barmerge barstate bgcolor bid box chart '
+    'close color currency dayofmonth dayofweek display dividends earnings extend fill fixnan font footprint '
+    'format high hl2 hlc3 hlcc4 hline hour input label last_bar_index last_bar_time line linefill location '
+    'log low map math matrix max_bars_back minute month na nz ohlc4 open order plot plotarrow plotbar '
+    'plotcandle plotchar plotshape polyline position request runtime scale script second session shape '
+    'size splits strategy string syminfo ta table text ticker time time_close time_tradingday timeframe '
+    'timenow timestamp volume weekofyear xloc year yloc').split())
+
+_MANAGED_PREFIXES = ('pynecore', 'dataclasses', 'enum')
+#: Names imported under an alias: name -> (module, imported name)
+KNOWN_ALIASES = {'_dataclass_field': ('dataclasses', 'field'), 'Enum': ('enum', 'StrEnum')}
+
+
+def _bound_names(tree: ast.Module) -> set[str]:
+    """Names the module binds itself (anywhere), which it must not import."""
+    bound: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            bound.add(node.name)
+        elif isinstance(node, ast.Name) and isinstance(node.ctx, ast.Store):
+            bound.add(node.id)
+        elif isinstance(node, ast.arg):
+            bound.add(node.arg)
+    return bound
+
+
+class ImportReconciliationPass:
+    """Drops imported names nothing uses, adds the ones a rewrite introduced,
+    and imports each from the module PyneComp takes it from (``NA`` from
+    ``pynecore.types``, not ``pynecore.lib``). Run it last."""
+
+    def apply(self, tree: ast.Module, context: PassContext) -> None:
+        imports = [node for node in tree.body if isinstance(node, ast.ImportFrom)]
+        managed = [node for node in imports if (node.module or '').startswith(_MANAGED_PREFIXES)]
+        used = {node.id for node in ast.walk(tree) if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Load)
+                and not getattr(node, 'added_default', False)}
+        used |= {decorator.id for node in ast.walk(tree)
+                 for decorator in getattr(node, 'decorator_list', []) if isinstance(decorator, ast.Name)}
+        local = _bound_names(tree) - {alias.asname or alias.name for node in imports for alias in node.names}
+
+        wanted: dict[str, list[str]] = {}
+        aliases: dict[str, list[ast.alias]] = {}
+        for node in managed:
+            for alias in node.names:
+                visible = alias.asname or alias.name
+                if visible not in used:
+                    continue
+                if alias.asname:
+                    aliases.setdefault(node.module, []).append(alias)
+                    continue
+                module = KNOWN_ORIGINS.get(alias.name, node.module)
+                wanted.setdefault(module, [])
+                if alias.name not in wanted[module]:
+                    wanted[module].append(alias.name)
+        already = {name for names in wanted.values() for name in names}
+        already |= {alias.asname for names in aliases.values() for alias in names}
+        for name in sorted(used - already - local - set(dir(builtins))):
+            if name in KNOWN_ALIASES:
+                module, imported = KNOWN_ALIASES[name]
+                aliases.setdefault(module, []).append(ast.alias(name=imported, asname=name))
+                continue
+            module = KNOWN_ORIGINS.get(name) or ('pynecore.lib' if name in LIB_NAMES else None)
+            if module:
+                wanted.setdefault(module, []).append(name)
+
+        rebuilt = [ast.ImportFrom(module=module, names=[ast.alias(name=name) for name in names]
+                                  + aliases.pop(module, []), level=0)
+                   for module, names in wanted.items() if names]
+        rebuilt += [ast.ImportFrom(module=module, names=names, level=0) for module, names in aliases.items()]
+        first = next((index for index, node in enumerate(tree.body) if node in managed), None)
+        tree.body[:] = [node for node in tree.body if node not in managed]
+        if rebuilt:
+            position = first if first is not None else _after_docstring(tree)
+            tree.body[position:position] = rebuilt
+
+
+def _after_docstring(tree: ast.Module) -> int:
+    body = tree.body
+    if body and isinstance(body[0], ast.Expr) and isinstance(body[0].value, ast.Constant):
+        return 1
+    return 0

pine2pyne/emit/pynecomp/passes/legacy_colors.py

@@ -0,0 +1,101 @@
+"""Pine v4 transparency, merged into the colour the way PyneComp merges it."""
+from __future__ import annotations
+
+import ast
+import re
+
+from .base import PassContext, function_scopes, own_nodes
+
+_HEX_COLOR = re.compile(r'#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})')
+_COLOR_KEYWORDS = {
+    'plot': ('color',), 'plotshape': ('color', 'textcolor'), 'plotchar': ('color',),
+    'plotarrow': ('colorup', 'colordown'), 'fill': ('color',),
+}
+#: v4 positional parameters: (index of color, index of transp)
+_POSITIONAL = {'plot': (2, None), 'plotshape': (4, 5), 'plotchar': (4, 5), 'fill': (2, 3)}
+#: v4's default ``transp`` of the functions that had the argument
+_DEFAULT_TRANSPARENCY = {'plot': 0, 'plotshape': 0, 'plotchar': 0, 'plotarrow': 0, 'fill': 90}
+
+
+#: Pine's named colour constants
+COLOUR_CONSTANTS = frozenset({
+    'aqua', 'black', 'blue', 'fuchsia', 'gray', 'green', 'lime', 'maroon', 'navy', 'olive', 'orange',
+    'purple', 'red', 'silver', 'teal', 'white', 'yellow'})
+
+
+def _is_constant_colour(node: ast.expr) -> bool:
+    """A hex literal or a named constant (``color.red``)."""
+    if isinstance(node, ast.Constant):
+        return isinstance(node.value, str) and bool(_HEX_COLOR.fullmatch(node.value))
+    return (isinstance(node, ast.Attribute) and isinstance(node.value, ast.Name)
+            and node.value.id == 'color' and node.attr in COLOUR_CONSTANTS)
+
+
+def _is_colour_constructor(call: ast.Call) -> bool:
+    """`color.new(c, transp=85)`: there transp is the colour's own argument."""
+    return (isinstance(call.func, ast.Attribute) and isinstance(call.func.value, ast.Name)
+            and call.func.value.id == 'color' and call.func.attr in ('new', 'rgb'))
+
+
+def _wrap(colour: ast.expr, transparency: ast.expr) -> ast.Call:
+    return ast.Call(func=ast.Attribute(value=ast.Name(id='color', ctx=ast.Load()), attr='new', ctx=ast.Load()),
+                    args=[colour, transparency], keywords=[])
+
+
+class LegacyTransparencyPass:
+    """Pine v4 ``plot(..., color=c, transp=t)`` is ``color=color.new(c, t)``; with no
+    ``transp`` a constant colour takes v4's default (``0``, ``90`` for ``fill``).
+    A name bound once to a constant colour counts as one; a series colour (a
+    conditional, a call) keeps its value, and ``transp`` is dropped
+    (about 1100 v4 call sites of the reference follow this)."""
+
+    def apply(self, tree: ast.Module, context: PassContext) -> None:
+        if context.pine_version >= 5:  # transp is gone: dropped, not merged
+            for node in ast.walk(tree):
+                if isinstance(node, ast.Call) and not _is_colour_constructor(node):
+                    node.keywords = [keyword for keyword in node.keywords if keyword.arg != 'transp']
+            return
+        for scope in function_scopes(tree):
+            constants = self._constant_colour_names(scope)
+            for node in own_nodes(scope):
+                if isinstance(node, ast.Call) and isinstance(node.func, ast.Name) \
+                        and node.func.id in _COLOR_KEYWORDS:
+                    self._merge(node, constants)
+        for node in ast.walk(tree):  # transp of any other call (bgcolor, ...) has no equivalent
+            if isinstance(node, ast.Call) and not _is_colour_constructor(node):
+                node.keywords = [keyword for keyword in node.keywords if keyword.arg != 'transp']
+
+    @staticmethod
+    def _constant_colour_names(scope: ast.AST) -> set[str]:
+        bindings: dict[str, list[ast.expr]] = {}
+        for node in own_nodes(scope):
+            if isinstance(node, (ast.Assign, ast.AnnAssign)) and node.value is not None:
+                targets = node.targets if isinstance(node, ast.Assign) else [node.target]
+                for target in targets:
+                    if isinstance(target, ast.Name):
+                        bindings.setdefault(target.id, []).append(node.value)
+        return {name for name, values in bindings.items()
+                if len(values) == 1 and _is_constant_colour(values[0])}
+
+    @staticmethod
+    def _merge(call: ast.Call, constants: set[str]) -> None:
+        function = call.func.id
+        transparency = next((keyword.value for keyword in call.keywords if keyword.arg == 'transp'), None)
+        call.keywords = [keyword for keyword in call.keywords if keyword.arg != 'transp']
+        colour_index, transp_index = _POSITIONAL.get(function, (None, None))
+        if transp_index is not None and len(call.args) > transp_index:
+            transparency = call.args.pop(transp_index)
+
+        def merged(value: ast.expr) -> ast.expr:
+            constant = _is_constant_colour(value) or (isinstance(value, ast.Name) and value.id in constants)
+            if constant:
+                return _wrap(value, transparency or ast.Constant(_DEFAULT_TRANSPARENCY[function]))
+            if transparency is not None and function == 'fill' and not isinstance(value, ast.Constant):
+                return _wrap(value, transparency)
+            return value
+
+        if colour_index is not None and len(call.args) > colour_index:
+            call.args[colour_index] = merged(call.args[colour_index])
+        for keyword in call.keywords:
+            if keyword.arg in _COLOR_KEYWORDS[function]:
+                keyword.value = merged(keyword.value)

pine2pyne/emit/pynecomp/passes/library.py

@@ -0,0 +1,205 @@
+"""A library's module laid out the way PyneComp lays it out.
+
+Measured on the 85 libraries of ``assets/pyne`` and probe scripts compiled by
+PyneComp v6.0.80 (``assets/probes/lib*``)::
+
+    <imports>
+    from typing import Protocol, Any
+
+    __all__ = [...]                       every exported name, emitted spelling, sorted
+
+    <enums and UDT classes, in source order>
+
+    class _ProtocolInit(Protocol):        one per exported function or method, source order
+        def __call__(self, <its parameters>) -> Any: ...
+
+    init: _ProtocolInit = Exported()      one per exported function or method
+
+    <module constants>
+
+    @script.library(...)
+    def main(): ...                       @export, @overload, @method in that order
+
+A protocol is named ``_Protocol`` + the function's name with each ``_``-part
+capitalised at its first letter (``get_sec_in_day`` -> ``GetSecInDay``, ``renderOnly`` ->
+``Renderonly``, ``trailing_3step`` -> ``Trailing3Step``); a
+name that already has one gets the protocol's 0-based index across the module
+as a suffix (``_ProtocolInit38``). Its parameters are the function's, but a
+default of ``na`` (one Python needs after a defaulted parameter) is ``...`` and
+a ``Series[T]`` the function's body earned by reading the parameter's history
+is ``T`` (a parameter declared ``series T`` keeps ``Series[T]``).
+"""
+from __future__ import annotations
+
+import ast
+import copy
+import re
+
+from .base import PassContext, main_function
+
+_DECORATOR_ORDER = {'export': 0, 'overload': 1, 'method': 2}
+_EXPORTED_TYPE = re.compile(r'^export\s+(?:type|enum)\s+(\w+)', re.M)
+
+
+def _source_position(node: ast.ClassDef, context: PassContext) -> int:
+    """Where the Pine source declares the `type`/`enum` a class is generated from."""
+    match = re.search(rf'^(?:export\s+)?(?:type|enum)\s+{re.escape(_pine_name(node.name))}\b',
+                      context.unit.pine_source or '', re.M)
+    return match.start() if match else 0
+
+
+def _capitalised(part: str) -> str:
+    """The first letter upper case, the rest lower case: `3step` -> `3Step`, `is2Tap` -> `Is2tap`."""
+    match = re.search(r'[A-Za-z]', part)
+    if not match:
+        return part
+    start = match.start()
+    return part[:start] + part[start].upper() + part[start + 1:].lower()
+
+
+def protocol_stem(name: str) -> str:
+    """`get_sec_in_day` -> `GetSecInDay`, `trailing_3step` -> `Trailing3Step`; a renamed function keeps its
+    Pine name (`fill__ren__` -> `Fill`)."""
+    name = re.sub(r'__ren__$|__global__$', '', name)
+    return ''.join(_capitalised(part) for part in name.split('_'))
+
+
+def _pine_name(name: str) -> str:
+    """The Pine name of a renamed parameter (`format__ren__`, `adr__00000017__` -> `format`, `adr`)."""
+    return re.sub(r'__ren__$|__global__$|__[0-9a-f]{8}__$', '', name)
+
+
+def _is_exported(node: ast.AST) -> bool:
+    return isinstance(node, ast.FunctionDef) and any(
+        isinstance(decorator, ast.Name) and decorator.id == 'export' for decorator in node.decorator_list)
+
+
+def _is_library(tree: ast.Module) -> bool:
+    main = main_function(tree)
+    return main is not None and any(
+        isinstance(decorator, ast.Call) and isinstance(decorator.func, ast.Attribute)
+        and decorator.func.attr == 'library' for decorator in main.decorator_list)
+
+
+def _exported_call(node: ast.stmt) -> bool:
+    value = getattr(node, 'value', None)
+    return isinstance(value, ast.Call) and isinstance(value.func, ast.Name) and value.func.id == 'Exported'
+
+
+def _assigns_all(node: ast.stmt) -> bool:
+    return isinstance(node, ast.Assign) and any(isinstance(target, ast.Name) and target.id == '__all__'
+                                                for target in node.targets)
+
+
+class LibraryPreamblePass:
+    """``__all__``, the ``_Protocol*`` classes and the ``Exported()`` declarations of a library."""
+
+    def apply(self, tree: ast.Module, context: PassContext) -> None:
+        main = main_function(tree)
+        if main is None:
+            return
+        for node in ast.walk(main):  # PyneComp's decorator order, any script
+            if isinstance(node, ast.FunctionDef) and len(node.decorator_list) > 1:
+                node.decorator_list.sort(key=lambda decorator: _DECORATOR_ORDER.get(
+                    getattr(decorator, 'id', ''), -1))
+        if not _is_library(tree):
+            self._classes_before_constants(tree, context)
+            return
+        exported = [node for node in main.body if _is_exported(node)]
+        declared = self._declared_parameters(context, len(exported))
+        protocols, declarations, seen = [], [], set()
+        for index, function in enumerate(exported):
+            name = f'_Protocol{protocol_stem(function.name)}'
+            if name in seen:
+                name = f'{name}{index}'
+            seen.add(f'_Protocol{protocol_stem(function.name)}')
+            protocols.append(self._protocol(name, function, *declared[index]))
+            declarations.append(ast.AnnAssign(target=ast.Name(id=function.name, ctx=ast.Store()),
+                                              annotation=ast.Name(id=name, ctx=ast.Load()),
+                                              value=ast.Call(func=ast.Name(id='Exported', ctx=ast.Load()),
+                                                             args=[], keywords=[]), simple=1))
+        exported_types = set(_EXPORTED_TYPE.findall(context.unit.pine_source or ''))
+        classes = [node for node in tree.body if isinstance(node, ast.ClassDef)]
+        public = {function.name for function in exported} | {node.name for node in classes
+                                                              if _pine_name(node.name) in exported_types}
+        names = ast.Assign(targets=[ast.Name(id='__all__', ctx=ast.Store())],
+                           value=ast.List(elts=[ast.Constant(name) for name in sorted(public)], ctx=ast.Load()))
+
+        imports = [node for node in tree.body if isinstance(node, (ast.Import, ast.ImportFrom))]
+        docstring = tree.body[:1] if tree.body and isinstance(tree.body[0], ast.Expr) else []
+        rest = [node for node in tree.body if node not in imports and node not in docstring
+                and not _exported_call(node) and not _assigns_all(node)]
+        # a library alias shadowing a builtin namespace (`ta__ren__ = shadowed_namespace(...)`) comes right after
+        # __all__ (TradingView/TechnicalRating)
+        shadowing = [node for node in rest if isinstance(node, ast.Assign) and isinstance(node.value, ast.Call)
+                     and isinstance(node.value.func, ast.Name) and node.value.func.id == 'shadowed_namespace']
+        constants = [node for node in rest if isinstance(node, (ast.Assign, ast.AnnAssign)) and node not in shadowing]
+        tail = [node for node in rest if node not in classes and node not in constants and node not in shadowing]
+        classes.sort(key=lambda node: _source_position(node, context))
+        if protocols:
+            typing = ast.ImportFrom(module='typing', names=[ast.alias(name='Protocol'), ast.alias(name='Any')],
+                                    level=0)
+            imports.append(typing)
+        for node in [names, *protocols, *declarations, *imports]:
+            for child in ast.walk(node):  # new nodes have no source position: line 0 maps to no Pine line
+                for attribute in ('lineno', 'col_offset', 'end_lineno', 'end_col_offset'):
+                    if not hasattr(child, attribute) and attribute in child._attributes:
+                        setattr(child, attribute, 0)
+        tree.body[:] = docstring + imports + ([names] if public else []) + shadowing + classes + protocols \
+            + declarations + constants + tail
+
+    @staticmethod
+    def _classes_before_constants(tree: ast.Module, context: PassContext) -> None:
+        """A script's enums and UDTs, in source order, come before its module constants
+        (probe enum1, PyneComp v6.0.80)."""
+        classes = [node for node in tree.body if isinstance(node, ast.ClassDef)]
+        if not classes:
+            return
+        main = main_function(tree)
+        before_main = tree.body[:tree.body.index(main)] if main in tree.body else list(tree.body)
+        movable = [node for node in before_main if isinstance(node, (ast.Assign, ast.AnnAssign))
+                   and not (isinstance(node.value, ast.Call) and isinstance(node.value.func, ast.Name)
+                            and node.value.func.id == 'shadowed_namespace')]
+        moved = set(map(id, classes + movable))
+        position = min(index for index, node in enumerate(tree.body) if id(node) in moved)
+        classes.sort(key=lambda node: _source_position(node, context))
+        rest = [node for node in tree.body if id(node) not in moved]
+        rest[position:position] = classes + movable
+        tree.body[:] = rest
+
+    @staticmethod
+    def _declared_parameters(context: PassContext, count: int) -> list[tuple[set[str], set[int]]]:
+        """Per exported function, in order: its parameters declared `series T`, and the positions
+        of the parameters the source gives no default (Python's `na` there is PyneComp's `...`)."""
+        empty = [(set(), set()) for _ in range(count)]
+        script = context.unit.pine_script
+        if script is None:
+            return empty
+        from ....ast_nodes import FuncDecl
+        functions = sorted((node for node in list(script.declarations) + list(script.body)
+                            if isinstance(node, FuncDecl) and node.is_export), key=lambda node: node.line)
+        found = [({parameter.name for parameter in function.params if parameter.is_series},
+                  {position for position, parameter in enumerate(function.params) if parameter.default is None})
+                 for function in functions]
+        return (found + empty)[:count]
+
+    @staticmethod
+    def _protocol(name: str, function: ast.FunctionDef, declared_series: set[str],
+                  undefaulted: set[int]) -> ast.ClassDef:
+        arguments = copy.deepcopy(function.args)
+        arguments.defaults = list(function.args.defaults)  # the same nodes: a default keeps its spelling
+        for argument in arguments.args:
+            annotation = argument.annotation
+            if (isinstance(annotation, ast.Subscript) and isinstance(annotation.value, ast.Name)
+                    and annotation.value.id == 'Series' and _pine_name(argument.arg) not in declared_series):
+                argument.annotation = annotation.slice  # the Series of a history read, not a declared one
+        first_default = len(arguments.args) - len(arguments.defaults)
+        arguments.defaults = [ast.Constant(...) if first_default + offset in undefaulted
+                              and isinstance(default, ast.Name) and default.id == 'na' else default
+                              for offset, default in enumerate(arguments.defaults)]
+        arguments.args.insert(0, ast.arg(arg='self'))
+        call = ast.FunctionDef(name='__call__', args=arguments, body=[ast.Expr(value=ast.Constant(...))],
+                               decorator_list=[], returns=ast.Name(id='Any', ctx=ast.Load()), type_params=[])
+        call.protocol_call = True  # printed `def __call__(self, <parameters>) -> Any: ...`, `self, ` even alone
+        return ast.ClassDef(name=name, bases=[ast.Name(id='Protocol', ctx=ast.Load())], keywords=[],
+                            body=[call], decorator_list=[], type_params=[])