@suss/adapter-python 0.35.1 → 0.37.0

package/dist/index.d.cts

@@ -1,9 +1,9 @@
-import { RequestSpellingMetadata, TypeShape, WrapperReference, BehavioralSummary } from '@suss/behavioral-ir';
+import { RequestSpellingMetadata, MessageBusTechnology, TypeShape, WrapperReference, BehavioralSummary } from '@suss/behavioral-ir';
 import { Tree, Node } from 'web-tree-sitter';
 export { Node as PyNode, Tree as PyTree } from 'web-tree-sitter';
 import { Database } from '@suss/datalog';
-import { RedirectOption, RawCodeStructure, ExtractorOptions, TimingReport, ExtractionReport, CacheDiagnostic, DeclaredModule, KeptParses } from '@suss/extractor';
-import { UnwrapsByName, WhyExplained } from '@suss/resolution';
+import { DeclaredEntryPoint, LibraryEnvVars, RedirectOption, RawCodeStructure, ExtractorOptions, TimingReport, ExtractionReport, CacheDiagnostic, DeclaredModule, KeptParses } from '@suss/extractor';
+import { UnwrapsByName, SubclassPlace, WhyExplained } from '@suss/resolution';
 
 /**
  * Loads the Python grammar into web-tree-sitter and parses a file.
@@ -105,6 +105,14 @@ interface PythonPack {
     /** Wire protocol for the produced boundary bindings, e.g. "http". */
     protocol: string;
     discovery: PythonDiscoveryPattern[];
+    /**
+     * The functions a deploy manifest says the platform calls in a file,
+     * given the file's absolute path. The adapter builds the units on each
+     * function it finds by name, and the call walk starts there.
+     */
+    entryPoints?: (file: string) => DeclaredEntryPoint[];
+    /** Environment variables the library reads from its own installed code, where no walk over the project goes. */
+    libraryEnvVars?: LibraryEnvVars[];
     /**
      * Wrapper modules around the library that a person lists when
      * configuring the pack. The library's own module does not go here. The adapter
@@ -137,6 +145,70 @@ interface PythonPack {
     requestSpelling?: RequestSpellingMetadata;
     /** How the library's test runner collects tests, so a PRD scenario can say which test covers it. */
     tests?: PyTestCases[];
+    /** How the library runs a project function as a background job, and the calls that enqueue one. DESIGN.md says how each is read. */
+    jobQueues?: PyJobQueue[];
+}
+/**
+ * A library that runs a project's functions off a queue, such as Celery.
+ * A function under one of `taskDecorators` becomes a consumer unit, and a
+ * call that enqueues it becomes a `message-send` on the same channel.
+ * Every name here is one the library defines.
+ */
+interface PyJobQueue {
+    /** The bus the bindings say, `celery`. */
+    messageBus: MessageBusTechnology;
+    /** The module the library's decorators and app class come from, `celery`. */
+    module: string;
+    /** Decorators that make a function a task: `shared_task`, and `task` on the app. */
+    taskDecorators: string[];
+    /** The keyword a task decorator takes the task's name under: `name`. */
+    nameKeyword: string;
+    /** The keyword a task decorator takes its queue under: `queue`. */
+    queueKeyword: string;
+    /** What the library calls a task whose decorator gives no name. */
+    defaultName: PyDefaultTaskName;
+    /** Methods on a task that enqueue it, and where each takes the task's arguments. */
+    enqueueMethods: PyEnqueueMethod[];
+    /** Methods on the app that enqueue a task by its name, `send_task`. */
+    sendByName?: PySendByName[];
+    /** The app's class, and the objects the module exports that stand for the app: `Celery`, `current_app`. */
+    apps: string[];
+}
+/**
+ * `modulePath` is Celery's: the dotted path of the module the function
+ * is written in, a dot, and the function's name.
+ */
+type PyDefaultTaskName = "modulePath";
+/** Where a method takes one of its inputs: a position, a keyword, or both. */
+interface PyCallArgument {
+    argument?: number;
+    keyword?: string;
+}
+/**
+ * How an enqueue call passes the task's arguments. `spread` passes them
+ * as the call's own, `delay(a, b, c=1)`. `packed` passes the positional
+ * ones as one sequence and the keyword ones as one mapping,
+ * `apply_async((a, b), {"c": 1})`.
+ */
+type PyTaskArguments = {
+    type: "spread";
+} | {
+    type: "packed";
+    args: PyCallArgument;
+    kwargs: PyCallArgument;
+};
+interface PyEnqueueMethod {
+    /** The method's name, `delay`. */
+    method: string;
+    arguments: PyTaskArguments;
+}
+interface PySendByName {
+    /** The method's name, `send_task`. */
+    method: string;
+    /** Where it takes the task's name. */
+    name: PyCallArgument;
+    /** Where it takes the task's arguments. */
+    arguments: PyTaskArguments;
 }
 /**
  * How a test runner finds tests and what it runs around each one. Every
@@ -1033,6 +1105,12 @@ interface ReachedFunction {
     readonly name: string;
     /** `[name]` for a module function, `[Class, name]` for a method. */
     readonly exportPath: string[];
+    /** The subclass the method runs on, when the call reached it through a class that inherits it. Calls on `self` or `cls` then resolve against that class. */
+    readonly receiverClass?: PythonSubclass;
+}
+/** A class that inherits a method: its name, the file that declares it, and its key in the value facts. */
+interface PythonSubclass extends SubclassPlace {
+    readonly key: string;
 }
 
 /**
@@ -1521,4 +1599,4 @@ declare function pythonImportEvidence(options: PythonImportEvidenceOptions): Pro
  */
 declare const ADAPTER_VERSION = "0.1.0";
 
-export { ADAPTER_VERSION, type AnnotationContext, type Binding, type BoundPythonFile, type DecoratedClassRoute, type DecoratedFunctionRoute, type DecoratorArg, type DecoratorClassification, type DiscoveryOptions, type ExtractPythonOptions, type ExtractPythonResult, type FileFactsOptions, type KeptPythonParses, type ModuleBinding, type ModuleResolution, type ModuleResolverOptions, type MountObjectCarrier, type MountObjectPrefix, type MountPrefixEffect, type NoValuePrefix, type ParameterSource, type PathRepeatedSlashes, type PrefixTrailingSlash, type PyModelEntryFunction, type PyModelEntryMethod, type PyModelQueries, type PyStatusCall, type PyTestCases, type PyTestMocks, type PyTestSetUp, type PythonDiscoveryPattern, type PythonImportEvidence, type PythonImportEvidenceOptions, type PythonImportSite, type PythonPack, type PythonSourceRoots, type PythonValueHandle, PythonWhySession, type PythonWhySessionOptions, type RawSqlPattern, type RelativeModuleSpec, type RequestObject, type RouteConventions, type RoutePrefixResolution, type RouterComposition, type RouterIndex, type Scope, type ScopeKind, type SqlCallArgument, type SqlClientHandoff, type SqlClientPattern, type SqlStatementCall, type SqlTableCall, type StoragePattern, type TomlFileRead, type TomlTable, type UnreadManifest, annotationToShape, bindModule, buildRouterIndex, classifyDecorator, containedValues, discoverUnits, emitModuleImportFacts, emitValueFacts, extractPythonProject, factsForFile, findPythonFiles, keptPythonParses, nameKeyIn, nodeId, objectReturnedBy, parsePython, parsePythonAhead, parsePythonSync, preloadPythonGrammar, pythonImportEvidence, pythonSourceRoots, readKey, readTomlFile, resolveAbsoluteModule, resolveCalls, resolveModule, resolveName, resolveRelativeModule, shapeFromName, tableAt };
+export { ADAPTER_VERSION, type AnnotationContext, type Binding, type BoundPythonFile, type DecoratedClassRoute, type DecoratedFunctionRoute, type DecoratorArg, type DecoratorClassification, type DiscoveryOptions, type ExtractPythonOptions, type ExtractPythonResult, type FileFactsOptions, type KeptPythonParses, type ModuleBinding, type ModuleResolution, type ModuleResolverOptions, type MountObjectCarrier, type MountObjectPrefix, type MountPrefixEffect, type NoValuePrefix, type ParameterSource, type PathRepeatedSlashes, type PrefixTrailingSlash, type PyCallArgument, type PyDefaultTaskName, type PyEnqueueMethod, type PyJobQueue, type PyModelEntryFunction, type PyModelEntryMethod, type PyModelQueries, type PySendByName, type PyStatusCall, type PyTaskArguments, type PyTestCases, type PyTestMocks, type PyTestSetUp, type PythonDiscoveryPattern, type PythonImportEvidence, type PythonImportEvidenceOptions, type PythonImportSite, type PythonPack, type PythonSourceRoots, type PythonValueHandle, PythonWhySession, type PythonWhySessionOptions, type RawSqlPattern, type RelativeModuleSpec, type RequestObject, type RouteConventions, type RoutePrefixResolution, type RouterComposition, type RouterIndex, type Scope, type ScopeKind, type SqlCallArgument, type SqlClientHandoff, type SqlClientPattern, type SqlStatementCall, type SqlTableCall, type StoragePattern, type TomlFileRead, type TomlTable, type UnreadManifest, annotationToShape, bindModule, buildRouterIndex, classifyDecorator, containedValues, discoverUnits, emitModuleImportFacts, emitValueFacts, extractPythonProject, factsForFile, findPythonFiles, keptPythonParses, nameKeyIn, nodeId, objectReturnedBy, parsePython, parsePythonAhead, parsePythonSync, preloadPythonGrammar, pythonImportEvidence, pythonSourceRoots, readKey, readTomlFile, resolveAbsoluteModule, resolveCalls, resolveModule, resolveName, resolveRelativeModule, shapeFromName, tableAt };

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import { RequestSpellingMetadata, TypeShape, WrapperReference, BehavioralSummary } from '@suss/behavioral-ir';
+import { RequestSpellingMetadata, MessageBusTechnology, TypeShape, WrapperReference, BehavioralSummary } from '@suss/behavioral-ir';
 import { Tree, Node } from 'web-tree-sitter';
 export { Node as PyNode, Tree as PyTree } from 'web-tree-sitter';
 import { Database } from '@suss/datalog';
-import { RedirectOption, RawCodeStructure, ExtractorOptions, TimingReport, ExtractionReport, CacheDiagnostic, DeclaredModule, KeptParses } from '@suss/extractor';
-import { UnwrapsByName, WhyExplained } from '@suss/resolution';
+import { DeclaredEntryPoint, LibraryEnvVars, RedirectOption, RawCodeStructure, ExtractorOptions, TimingReport, ExtractionReport, CacheDiagnostic, DeclaredModule, KeptParses } from '@suss/extractor';
+import { UnwrapsByName, SubclassPlace, WhyExplained } from '@suss/resolution';
 
 /**
  * Loads the Python grammar into web-tree-sitter and parses a file.
@@ -105,6 +105,14 @@ interface PythonPack {
     /** Wire protocol for the produced boundary bindings, e.g. "http". */
     protocol: string;
     discovery: PythonDiscoveryPattern[];
+    /**
+     * The functions a deploy manifest says the platform calls in a file,
+     * given the file's absolute path. The adapter builds the units on each
+     * function it finds by name, and the call walk starts there.
+     */
+    entryPoints?: (file: string) => DeclaredEntryPoint[];
+    /** Environment variables the library reads from its own installed code, where no walk over the project goes. */
+    libraryEnvVars?: LibraryEnvVars[];
     /**
      * Wrapper modules around the library that a person lists when
      * configuring the pack. The library's own module does not go here. The adapter
@@ -137,6 +145,70 @@ interface PythonPack {
     requestSpelling?: RequestSpellingMetadata;
     /** How the library's test runner collects tests, so a PRD scenario can say which test covers it. */
     tests?: PyTestCases[];
+    /** How the library runs a project function as a background job, and the calls that enqueue one. DESIGN.md says how each is read. */
+    jobQueues?: PyJobQueue[];
+}
+/**
+ * A library that runs a project's functions off a queue, such as Celery.
+ * A function under one of `taskDecorators` becomes a consumer unit, and a
+ * call that enqueues it becomes a `message-send` on the same channel.
+ * Every name here is one the library defines.
+ */
+interface PyJobQueue {
+    /** The bus the bindings say, `celery`. */
+    messageBus: MessageBusTechnology;
+    /** The module the library's decorators and app class come from, `celery`. */
+    module: string;
+    /** Decorators that make a function a task: `shared_task`, and `task` on the app. */
+    taskDecorators: string[];
+    /** The keyword a task decorator takes the task's name under: `name`. */
+    nameKeyword: string;
+    /** The keyword a task decorator takes its queue under: `queue`. */
+    queueKeyword: string;
+    /** What the library calls a task whose decorator gives no name. */
+    defaultName: PyDefaultTaskName;
+    /** Methods on a task that enqueue it, and where each takes the task's arguments. */
+    enqueueMethods: PyEnqueueMethod[];
+    /** Methods on the app that enqueue a task by its name, `send_task`. */
+    sendByName?: PySendByName[];
+    /** The app's class, and the objects the module exports that stand for the app: `Celery`, `current_app`. */
+    apps: string[];
+}
+/**
+ * `modulePath` is Celery's: the dotted path of the module the function
+ * is written in, a dot, and the function's name.
+ */
+type PyDefaultTaskName = "modulePath";
+/** Where a method takes one of its inputs: a position, a keyword, or both. */
+interface PyCallArgument {
+    argument?: number;
+    keyword?: string;
+}
+/**
+ * How an enqueue call passes the task's arguments. `spread` passes them
+ * as the call's own, `delay(a, b, c=1)`. `packed` passes the positional
+ * ones as one sequence and the keyword ones as one mapping,
+ * `apply_async((a, b), {"c": 1})`.
+ */
+type PyTaskArguments = {
+    type: "spread";
+} | {
+    type: "packed";
+    args: PyCallArgument;
+    kwargs: PyCallArgument;
+};
+interface PyEnqueueMethod {
+    /** The method's name, `delay`. */
+    method: string;
+    arguments: PyTaskArguments;
+}
+interface PySendByName {
+    /** The method's name, `send_task`. */
+    method: string;
+    /** Where it takes the task's name. */
+    name: PyCallArgument;
+    /** Where it takes the task's arguments. */
+    arguments: PyTaskArguments;
 }
 /**
  * How a test runner finds tests and what it runs around each one. Every
@@ -1033,6 +1105,12 @@ interface ReachedFunction {
     readonly name: string;
     /** `[name]` for a module function, `[Class, name]` for a method. */
     readonly exportPath: string[];
+    /** The subclass the method runs on, when the call reached it through a class that inherits it. Calls on `self` or `cls` then resolve against that class. */
+    readonly receiverClass?: PythonSubclass;
+}
+/** A class that inherits a method: its name, the file that declares it, and its key in the value facts. */
+interface PythonSubclass extends SubclassPlace {
+    readonly key: string;
 }
 
 /**
@@ -1521,4 +1599,4 @@ declare function pythonImportEvidence(options: PythonImportEvidenceOptions): Pro
  */
 declare const ADAPTER_VERSION = "0.1.0";
 
-export { ADAPTER_VERSION, type AnnotationContext, type Binding, type BoundPythonFile, type DecoratedClassRoute, type DecoratedFunctionRoute, type DecoratorArg, type DecoratorClassification, type DiscoveryOptions, type ExtractPythonOptions, type ExtractPythonResult, type FileFactsOptions, type KeptPythonParses, type ModuleBinding, type ModuleResolution, type ModuleResolverOptions, type MountObjectCarrier, type MountObjectPrefix, type MountPrefixEffect, type NoValuePrefix, type ParameterSource, type PathRepeatedSlashes, type PrefixTrailingSlash, type PyModelEntryFunction, type PyModelEntryMethod, type PyModelQueries, type PyStatusCall, type PyTestCases, type PyTestMocks, type PyTestSetUp, type PythonDiscoveryPattern, type PythonImportEvidence, type PythonImportEvidenceOptions, type PythonImportSite, type PythonPack, type PythonSourceRoots, type PythonValueHandle, PythonWhySession, type PythonWhySessionOptions, type RawSqlPattern, type RelativeModuleSpec, type RequestObject, type RouteConventions, type RoutePrefixResolution, type RouterComposition, type RouterIndex, type Scope, type ScopeKind, type SqlCallArgument, type SqlClientHandoff, type SqlClientPattern, type SqlStatementCall, type SqlTableCall, type StoragePattern, type TomlFileRead, type TomlTable, type UnreadManifest, annotationToShape, bindModule, buildRouterIndex, classifyDecorator, containedValues, discoverUnits, emitModuleImportFacts, emitValueFacts, extractPythonProject, factsForFile, findPythonFiles, keptPythonParses, nameKeyIn, nodeId, objectReturnedBy, parsePython, parsePythonAhead, parsePythonSync, preloadPythonGrammar, pythonImportEvidence, pythonSourceRoots, readKey, readTomlFile, resolveAbsoluteModule, resolveCalls, resolveModule, resolveName, resolveRelativeModule, shapeFromName, tableAt };
+export { ADAPTER_VERSION, type AnnotationContext, type Binding, type BoundPythonFile, type DecoratedClassRoute, type DecoratedFunctionRoute, type DecoratorArg, type DecoratorClassification, type DiscoveryOptions, type ExtractPythonOptions, type ExtractPythonResult, type FileFactsOptions, type KeptPythonParses, type ModuleBinding, type ModuleResolution, type ModuleResolverOptions, type MountObjectCarrier, type MountObjectPrefix, type MountPrefixEffect, type NoValuePrefix, type ParameterSource, type PathRepeatedSlashes, type PrefixTrailingSlash, type PyCallArgument, type PyDefaultTaskName, type PyEnqueueMethod, type PyJobQueue, type PyModelEntryFunction, type PyModelEntryMethod, type PyModelQueries, type PySendByName, type PyStatusCall, type PyTaskArguments, type PyTestCases, type PyTestMocks, type PyTestSetUp, type PythonDiscoveryPattern, type PythonImportEvidence, type PythonImportEvidenceOptions, type PythonImportSite, type PythonPack, type PythonSourceRoots, type PythonValueHandle, PythonWhySession, type PythonWhySessionOptions, type RawSqlPattern, type RelativeModuleSpec, type RequestObject, type RouteConventions, type RoutePrefixResolution, type RouterComposition, type RouterIndex, type Scope, type ScopeKind, type SqlCallArgument, type SqlClientHandoff, type SqlClientPattern, type SqlStatementCall, type SqlTableCall, type StoragePattern, type TomlFileRead, type TomlTable, type UnreadManifest, annotationToShape, bindModule, buildRouterIndex, classifyDecorator, containedValues, discoverUnits, emitModuleImportFacts, emitValueFacts, extractPythonProject, factsForFile, findPythonFiles, keptPythonParses, nameKeyIn, nodeId, objectReturnedBy, parsePython, parsePythonAhead, parsePythonSync, preloadPythonGrammar, pythonImportEvidence, pythonSourceRoots, readKey, readTomlFile, resolveAbsoluteModule, resolveCalls, resolveModule, resolveName, resolveRelativeModule, shapeFromName, tableAt };