@suss/adapter-python 0.36.0 → 0.37.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-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';
@@ -145,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
@@ -1535,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,4 +1,4 @@
-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';
@@ -145,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
@@ -1535,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 };