@suss/adapter-python 0.29.0 → 0.31.0

package/dist/index.d.cts

@@ -111,6 +111,8 @@ interface PythonPack {
     storage?: StoragePattern[];
     /** Which of the library's calls give back one of a model class. The README says what a chain of them composes into. */
     models?: PyModelQueries[];
+    /** Which of the library's classes return themselves from `__enter__`, so a `with` block gets the object itself. */
+    contextManagers?: PyContextManager[];
     /** How the library lets a project hand the database SQL it wrote itself. */
     rawSql?: RawSqlPattern[];
 }
@@ -170,6 +172,20 @@ interface PyModelQueries {
     entryMethods: PyModelEntryMethod[];
     /** Functions the library exports that do the same, called on their own rather than read off a session. */
     entryFunctions: PyModelEntryFunction[];
+    /** The library's own constructors for a field that reaches another model. */
+    relationships?: PyRelationshipConstructor[];
+}
+/**
+ * `items: list[Item] = Relationship(...)`: the callable a model's field
+ * is given to say it reaches another model, and where it comes from. A
+ * project function spelled the same way is somebody else's, so the
+ * import is what settles a match.
+ */
+interface PyRelationshipConstructor {
+    /** The module it is imported from, `sqlmodel` or `sqlalchemy.orm`. */
+    module: string;
+    /** Its name, `Relationship` or `relationship`. */
+    name: string;
 }
 /** `session.get(User, id)`: the method, and where the class is written. */
 interface PyModelEntryMethod {
@@ -197,6 +213,18 @@ interface RawSqlPattern {
     storageSystem: "postgresql" | "mysql" | "sqlite";
 }
 type PythonDiscoveryPattern = DecoratedClassRoute | DecoratedFunctionRoute;
+/**
+ * A class whose `__enter__` gives back the object it was called on, so
+ * `with X() as y` makes y the `X()` the block opened. Python
+ * lets `__enter__` return anything, so only the library that wrote the
+ * class can say this, and a pack declares it for its own classes alone.
+ */
+interface PyContextManager {
+    /** The module the classes come from, `httpx`. */
+    module: string;
+    /** The class names the library documents as returning self. */
+    returnsSelf: string[];
+}
 /**
  * The callables a library gives a project for making a request. A
  * function that calls one of them is a client of the boundary that call
@@ -516,6 +544,11 @@ type Binding = {
     module: string;
     relativeLevel: number;
     localName: string;
+    /**
+     * False for `import a.b.c`, where the name binds the package `a`
+     * and a member read off it lands somewhere other than `module`.
+     */
+    bindsWholeModule: boolean;
 } | {
     kind: "importFrom";
     module: string;
@@ -595,23 +628,11 @@ type RoutePrefixResolution = {
 interface RouterIndex {
     resolve(pattern: PythonDiscoveryPattern, module: ModuleBinding, objectName: string): RoutePrefixResolution;
     /**
-     * The same answer for a decorator whose object has no variable name to
-     * look up, such as one written on `self.router`. The rules give the call
-     * that built it, and every construction is already keyed by its call.
+     * The same for a decorator whose object has no variable name to look up,
+     * such as one written on `self.router`. The rules give the call that
+     * built it, and every construction is already keyed by its call.
      */
     resolveConstruction(pattern: PythonDiscoveryPattern, module: ModuleBinding, constructorName: string, constructionKey: string): RoutePrefixResolution;
-    /**
-     * The module-level def a name in another module refers to, with that
-     * module's own bindings, so a decorator written through a project wrapper
-     * can be read where the wrapper is written.
-     */
-    moduleDef(fromFile: string, spec: {
-        module: string;
-        relativeLevel: number;
-    }, name: string): {
-        node: Node;
-        module: ModuleBinding;
-    } | null;
 }
 interface RouterIndexOptions extends ModuleResolverOptions {
     /** The project's facts, so a loop over a call can be settled by the rules. */
@@ -713,7 +734,6 @@ interface DecoratorClassification {
     module: string | null;
     /** The local variable an attribute decorator hangs on, `app` in `@app.get(...)`. */
     objectName: string | null;
-    relativeLevel: number;
     args: DecoratorArg[];
     keywordArgs: Record<string, DecoratorArg>;
     /** Where the decorator is written. Anything we read out of its arguments uses this as its provenance. */
@@ -725,16 +745,16 @@ interface DecoratorClassification {
      */
     objectModule?: ModuleBinding;
     /**
-     * The call the rules say built the object this decorator hangs on, when
-     * the lexical scope could not say. A router prefix is looked up by this
-     * call rather than by a variable name, because there may not be one.
+     * The call the rules say built the object this decorator hangs on. A
+     * router the index never saw under a name is looked up by this call
+     * instead, and a decorator on `self.router` has no name to look up.
      */
     subjectConstruction?: {
         key: string;
         constructorName: string;
     };
 }
-declare function classifyDecorator(decoratorNode: Node, scope: Scope): DecoratorClassification;
+declare function classifyDecorator(decoratorNode: Node, module: ModuleBinding, facts?: Database): DecoratorClassification;
 
 /**
  * What discovery uses for one file. `factsPath` is the path the facts were
@@ -1028,6 +1048,22 @@ interface ExtractPythonResult {
     summaries: BehavioralSummary[];
     facts: Database;
 }
+/** One parsed file and the packs a run over it would load. */
+interface FileFactsOptions {
+    file: string;
+    root: Node;
+    module: ModuleBinding;
+    packs: readonly PythonPack[];
+}
+/**
+ * The facts for a single parsed file, with the evaluator bound to them,
+ * for a caller that has one file and no project. A pack's own tests need
+ * these: what built a receiver is an answer the rules give, and without
+ * facts they have nothing to give it from. A project run emits the same
+ * facts across every file at once, so a name written in another file
+ * resolves there and never here.
+ */
+declare function factsForFile(options: FileFactsOptions): Database;
 declare function extractPythonProject(options: ExtractPythonOptions): Promise<ExtractPythonResult>;
 /** Every `.py` file under `root`, depth-first, skipping the usual non-source directories. */
 declare function findPythonFiles(root: string): string[];
@@ -1076,4 +1112,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 ModuleBinding, type ModuleResolution, type ModuleResolverOptions, type MountObjectCarrier, type MountObjectPrefix, type MountPrefixEffect, type NoValuePrefix, type PathRepeatedSlashes, type PrefixTrailingSlash, type PyModelEntryFunction, type PyModelEntryMethod, type PyModelQueries, type PyStatusCall, type PythonDiscoveryPattern, type PythonImportEvidence, type PythonImportEvidenceOptions, type PythonImportSite, type PythonPack, type PythonValueHandle, PythonWhySession, type PythonWhySessionOptions, type RawSqlPattern, type RelativeModuleSpec, type RouteConventions, type RoutePrefixResolution, type RouterComposition, type RouterIndex, type Scope, type ScopeKind, type StoragePattern, annotationToShape, bindModule, buildRouterIndex, classifyDecorator, containedValues, discoverUnits, emitEntryFact, emitModuleImportFacts, emitValueFacts, extractPythonProject, findPythonFiles, nameKeyIn, nodeId, objectReturnedBy, parsePython, parsePythonSync, preloadPythonGrammar, pythonImportEvidence, readKey, resolveAbsoluteModule, resolveCalls, resolveModule, resolveName, resolveRelativeModule, shapeFromName, unitKey };
+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 ModuleBinding, type ModuleResolution, type ModuleResolverOptions, type MountObjectCarrier, type MountObjectPrefix, type MountPrefixEffect, type NoValuePrefix, type PathRepeatedSlashes, type PrefixTrailingSlash, type PyModelEntryFunction, type PyModelEntryMethod, type PyModelQueries, type PyStatusCall, type PythonDiscoveryPattern, type PythonImportEvidence, type PythonImportEvidenceOptions, type PythonImportSite, type PythonPack, type PythonValueHandle, PythonWhySession, type PythonWhySessionOptions, type RawSqlPattern, type RelativeModuleSpec, type RouteConventions, type RoutePrefixResolution, type RouterComposition, type RouterIndex, type Scope, type ScopeKind, type StoragePattern, annotationToShape, bindModule, buildRouterIndex, classifyDecorator, containedValues, discoverUnits, emitEntryFact, emitModuleImportFacts, emitValueFacts, extractPythonProject, factsForFile, findPythonFiles, nameKeyIn, nodeId, objectReturnedBy, parsePython, parsePythonSync, preloadPythonGrammar, pythonImportEvidence, readKey, resolveAbsoluteModule, resolveCalls, resolveModule, resolveName, resolveRelativeModule, shapeFromName, unitKey };

package/dist/index.d.ts

@@ -111,6 +111,8 @@ interface PythonPack {
     storage?: StoragePattern[];
     /** Which of the library's calls give back one of a model class. The README says what a chain of them composes into. */
     models?: PyModelQueries[];
+    /** Which of the library's classes return themselves from `__enter__`, so a `with` block gets the object itself. */
+    contextManagers?: PyContextManager[];
     /** How the library lets a project hand the database SQL it wrote itself. */
     rawSql?: RawSqlPattern[];
 }
@@ -170,6 +172,20 @@ interface PyModelQueries {
     entryMethods: PyModelEntryMethod[];
     /** Functions the library exports that do the same, called on their own rather than read off a session. */
     entryFunctions: PyModelEntryFunction[];
+    /** The library's own constructors for a field that reaches another model. */
+    relationships?: PyRelationshipConstructor[];
+}
+/**
+ * `items: list[Item] = Relationship(...)`: the callable a model's field
+ * is given to say it reaches another model, and where it comes from. A
+ * project function spelled the same way is somebody else's, so the
+ * import is what settles a match.
+ */
+interface PyRelationshipConstructor {
+    /** The module it is imported from, `sqlmodel` or `sqlalchemy.orm`. */
+    module: string;
+    /** Its name, `Relationship` or `relationship`. */
+    name: string;
 }
 /** `session.get(User, id)`: the method, and where the class is written. */
 interface PyModelEntryMethod {
@@ -197,6 +213,18 @@ interface RawSqlPattern {
     storageSystem: "postgresql" | "mysql" | "sqlite";
 }
 type PythonDiscoveryPattern = DecoratedClassRoute | DecoratedFunctionRoute;
+/**
+ * A class whose `__enter__` gives back the object it was called on, so
+ * `with X() as y` makes y the `X()` the block opened. Python
+ * lets `__enter__` return anything, so only the library that wrote the
+ * class can say this, and a pack declares it for its own classes alone.
+ */
+interface PyContextManager {
+    /** The module the classes come from, `httpx`. */
+    module: string;
+    /** The class names the library documents as returning self. */
+    returnsSelf: string[];
+}
 /**
  * The callables a library gives a project for making a request. A
  * function that calls one of them is a client of the boundary that call
@@ -516,6 +544,11 @@ type Binding = {
     module: string;
     relativeLevel: number;
     localName: string;
+    /**
+     * False for `import a.b.c`, where the name binds the package `a`
+     * and a member read off it lands somewhere other than `module`.
+     */
+    bindsWholeModule: boolean;
 } | {
     kind: "importFrom";
     module: string;
@@ -595,23 +628,11 @@ type RoutePrefixResolution = {
 interface RouterIndex {
     resolve(pattern: PythonDiscoveryPattern, module: ModuleBinding, objectName: string): RoutePrefixResolution;
     /**
-     * The same answer for a decorator whose object has no variable name to
-     * look up, such as one written on `self.router`. The rules give the call
-     * that built it, and every construction is already keyed by its call.
+     * The same for a decorator whose object has no variable name to look up,
+     * such as one written on `self.router`. The rules give the call that
+     * built it, and every construction is already keyed by its call.
      */
     resolveConstruction(pattern: PythonDiscoveryPattern, module: ModuleBinding, constructorName: string, constructionKey: string): RoutePrefixResolution;
-    /**
-     * The module-level def a name in another module refers to, with that
-     * module's own bindings, so a decorator written through a project wrapper
-     * can be read where the wrapper is written.
-     */
-    moduleDef(fromFile: string, spec: {
-        module: string;
-        relativeLevel: number;
-    }, name: string): {
-        node: Node;
-        module: ModuleBinding;
-    } | null;
 }
 interface RouterIndexOptions extends ModuleResolverOptions {
     /** The project's facts, so a loop over a call can be settled by the rules. */
@@ -713,7 +734,6 @@ interface DecoratorClassification {
     module: string | null;
     /** The local variable an attribute decorator hangs on, `app` in `@app.get(...)`. */
     objectName: string | null;
-    relativeLevel: number;
     args: DecoratorArg[];
     keywordArgs: Record<string, DecoratorArg>;
     /** Where the decorator is written. Anything we read out of its arguments uses this as its provenance. */
@@ -725,16 +745,16 @@ interface DecoratorClassification {
      */
     objectModule?: ModuleBinding;
     /**
-     * The call the rules say built the object this decorator hangs on, when
-     * the lexical scope could not say. A router prefix is looked up by this
-     * call rather than by a variable name, because there may not be one.
+     * The call the rules say built the object this decorator hangs on. A
+     * router the index never saw under a name is looked up by this call
+     * instead, and a decorator on `self.router` has no name to look up.
      */
     subjectConstruction?: {
         key: string;
         constructorName: string;
     };
 }
-declare function classifyDecorator(decoratorNode: Node, scope: Scope): DecoratorClassification;
+declare function classifyDecorator(decoratorNode: Node, module: ModuleBinding, facts?: Database): DecoratorClassification;
 
 /**
  * What discovery uses for one file. `factsPath` is the path the facts were
@@ -1028,6 +1048,22 @@ interface ExtractPythonResult {
     summaries: BehavioralSummary[];
     facts: Database;
 }
+/** One parsed file and the packs a run over it would load. */
+interface FileFactsOptions {
+    file: string;
+    root: Node;
+    module: ModuleBinding;
+    packs: readonly PythonPack[];
+}
+/**
+ * The facts for a single parsed file, with the evaluator bound to them,
+ * for a caller that has one file and no project. A pack's own tests need
+ * these: what built a receiver is an answer the rules give, and without
+ * facts they have nothing to give it from. A project run emits the same
+ * facts across every file at once, so a name written in another file
+ * resolves there and never here.
+ */
+declare function factsForFile(options: FileFactsOptions): Database;
 declare function extractPythonProject(options: ExtractPythonOptions): Promise<ExtractPythonResult>;
 /** Every `.py` file under `root`, depth-first, skipping the usual non-source directories. */
 declare function findPythonFiles(root: string): string[];
@@ -1076,4 +1112,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 ModuleBinding, type ModuleResolution, type ModuleResolverOptions, type MountObjectCarrier, type MountObjectPrefix, type MountPrefixEffect, type NoValuePrefix, type PathRepeatedSlashes, type PrefixTrailingSlash, type PyModelEntryFunction, type PyModelEntryMethod, type PyModelQueries, type PyStatusCall, type PythonDiscoveryPattern, type PythonImportEvidence, type PythonImportEvidenceOptions, type PythonImportSite, type PythonPack, type PythonValueHandle, PythonWhySession, type PythonWhySessionOptions, type RawSqlPattern, type RelativeModuleSpec, type RouteConventions, type RoutePrefixResolution, type RouterComposition, type RouterIndex, type Scope, type ScopeKind, type StoragePattern, annotationToShape, bindModule, buildRouterIndex, classifyDecorator, containedValues, discoverUnits, emitEntryFact, emitModuleImportFacts, emitValueFacts, extractPythonProject, findPythonFiles, nameKeyIn, nodeId, objectReturnedBy, parsePython, parsePythonSync, preloadPythonGrammar, pythonImportEvidence, readKey, resolveAbsoluteModule, resolveCalls, resolveModule, resolveName, resolveRelativeModule, shapeFromName, unitKey };
+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 ModuleBinding, type ModuleResolution, type ModuleResolverOptions, type MountObjectCarrier, type MountObjectPrefix, type MountPrefixEffect, type NoValuePrefix, type PathRepeatedSlashes, type PrefixTrailingSlash, type PyModelEntryFunction, type PyModelEntryMethod, type PyModelQueries, type PyStatusCall, type PythonDiscoveryPattern, type PythonImportEvidence, type PythonImportEvidenceOptions, type PythonImportSite, type PythonPack, type PythonValueHandle, PythonWhySession, type PythonWhySessionOptions, type RawSqlPattern, type RelativeModuleSpec, type RouteConventions, type RoutePrefixResolution, type RouterComposition, type RouterIndex, type Scope, type ScopeKind, type StoragePattern, annotationToShape, bindModule, buildRouterIndex, classifyDecorator, containedValues, discoverUnits, emitEntryFact, emitModuleImportFacts, emitValueFacts, extractPythonProject, factsForFile, findPythonFiles, nameKeyIn, nodeId, objectReturnedBy, parsePython, parsePythonSync, preloadPythonGrammar, pythonImportEvidence, readKey, resolveAbsoluteModule, resolveCalls, resolveModule, resolveName, resolveRelativeModule, shapeFromName, unitKey };