@suss/adapter-python 0.22.1 → 0.22.3

package/dist/index.d.cts

@@ -125,7 +125,11 @@ interface Range {
     end: number;
 }
 
-type DecoratorArg = {
+/** An argument as written, plus its node so a reader can evaluate what it comes down to. */
+type DecoratorArg = DecoratorArgShape & {
+    readonly node: Node;
+};
+type DecoratorArgShape = {
     kind: "string";
     value: string;
 } | {
@@ -243,6 +247,20 @@ interface StoragePattern {
     queryTypes: string[];
     /** Chain-ending methods that change what is stored. Anything else reads. */
     writes: string[];
+    /**
+     * Methods on a query type that touch no rows of their own: one that runs
+     * a statement built elsewhere, `session.execute(stmt)`, whose own chain
+     * already records the work, and one that manages the session, `close`.
+     * A call to one of these records nothing.
+     */
+    recordsNothing?: string[];
+    /**
+     * Methods whose keywords supply column values rather than pick rows,
+     * `values` in `update(User).where(id=1).values(name="x")`. Their
+     * keywords are reported as fields; every other call's keywords are the
+     * selector.
+     */
+    valueMethods?: string[];
     /**
      * Functions the library exports that start a query on their own, for the
      * case where a call site imports one rather than reaching it through a
@@ -297,9 +315,32 @@ interface RouteConventions {
      * that sets its own status would be reported at the default.
      */
     statusFromReturnedTuple?: boolean;
+    /**
+     * The library's own callables that end the request with a status, such
+     * as FastAPI's `HTTPException` and Flask's `abort`. Declaring them is
+     * also what makes a `raise` in a route body an outcome of its own: a
+     * raise the list does not cover comes out as a throw with no status,
+     * and one it does cover comes out as the response the library sends.
+     */
+    responseStatusCalls?: PyStatusCall[];
     /** Unset means the library has no router mounting, and a route's decorator path stands as written. */
     routerComposition?: RouterComposition;
 }
+/**
+ * One callable that ends the request, and where it takes the status.
+ * A call may take it either way, so a pattern may state both, and the
+ * keyword wins where an argument is written both ways.
+ */
+interface PyStatusCall {
+    /** The callee as the file imports it, module and name together, `fastapi.HTTPException`. */
+    callee: string;
+    /** The keyword whose value gives the status, FastAPI's `status_code`. */
+    statusKeyword?: string;
+    /** The index of the positional argument giving the status, 0 for `abort(404)`. */
+    statusArgument?: number;
+    /** What the library sends when the call states no status of its own. */
+    defaultStatusCode?: number;
+}
 /**
  * A class has a decorator whose first string-literal argument is the route path,
  * and each method in its body named after an HTTP verb becomes its own unit,
@@ -745,4 +786,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 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, 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 ModuleBinding, type ModuleResolution, type ModuleResolverOptions, type MountObjectCarrier, type MountObjectPrefix, type MountPrefixEffect, type NoValuePrefix, type PathRepeatedSlashes, type PrefixTrailingSlash, 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, nodeId, objectReturnedBy, parsePython, parsePythonSync, preloadPythonGrammar, pythonImportEvidence, readKey, resolveAbsoluteModule, resolveCalls, resolveModule, resolveName, resolveRelativeModule, shapeFromName, unitKey };

package/dist/index.d.ts

@@ -125,7 +125,11 @@ interface Range {
     end: number;
 }
 
-type DecoratorArg = {
+/** An argument as written, plus its node so a reader can evaluate what it comes down to. */
+type DecoratorArg = DecoratorArgShape & {
+    readonly node: Node;
+};
+type DecoratorArgShape = {
     kind: "string";
     value: string;
 } | {
@@ -243,6 +247,20 @@ interface StoragePattern {
     queryTypes: string[];
     /** Chain-ending methods that change what is stored. Anything else reads. */
     writes: string[];
+    /**
+     * Methods on a query type that touch no rows of their own: one that runs
+     * a statement built elsewhere, `session.execute(stmt)`, whose own chain
+     * already records the work, and one that manages the session, `close`.
+     * A call to one of these records nothing.
+     */
+    recordsNothing?: string[];
+    /**
+     * Methods whose keywords supply column values rather than pick rows,
+     * `values` in `update(User).where(id=1).values(name="x")`. Their
+     * keywords are reported as fields; every other call's keywords are the
+     * selector.
+     */
+    valueMethods?: string[];
     /**
      * Functions the library exports that start a query on their own, for the
      * case where a call site imports one rather than reaching it through a
@@ -297,9 +315,32 @@ interface RouteConventions {
      * that sets its own status would be reported at the default.
      */
     statusFromReturnedTuple?: boolean;
+    /**
+     * The library's own callables that end the request with a status, such
+     * as FastAPI's `HTTPException` and Flask's `abort`. Declaring them is
+     * also what makes a `raise` in a route body an outcome of its own: a
+     * raise the list does not cover comes out as a throw with no status,
+     * and one it does cover comes out as the response the library sends.
+     */
+    responseStatusCalls?: PyStatusCall[];
     /** Unset means the library has no router mounting, and a route's decorator path stands as written. */
     routerComposition?: RouterComposition;
 }
+/**
+ * One callable that ends the request, and where it takes the status.
+ * A call may take it either way, so a pattern may state both, and the
+ * keyword wins where an argument is written both ways.
+ */
+interface PyStatusCall {
+    /** The callee as the file imports it, module and name together, `fastapi.HTTPException`. */
+    callee: string;
+    /** The keyword whose value gives the status, FastAPI's `status_code`. */
+    statusKeyword?: string;
+    /** The index of the positional argument giving the status, 0 for `abort(404)`. */
+    statusArgument?: number;
+    /** What the library sends when the call states no status of its own. */
+    defaultStatusCode?: number;
+}
 /**
  * A class has a decorator whose first string-literal argument is the route path,
  * and each method in its body named after an HTTP verb becomes its own unit,
@@ -745,4 +786,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 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, 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 ModuleBinding, type ModuleResolution, type ModuleResolverOptions, type MountObjectCarrier, type MountObjectPrefix, type MountPrefixEffect, type NoValuePrefix, type PathRepeatedSlashes, type PrefixTrailingSlash, 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, nodeId, objectReturnedBy, parsePython, parsePythonSync, preloadPythonGrammar, pythonImportEvidence, readKey, resolveAbsoluteModule, resolveCalls, resolveModule, resolveName, resolveRelativeModule, shapeFromName, unitKey };