@suss/adapter-python 0.34.0 → 0.34.1

package/dist/index.d.cts

@@ -2,8 +2,8 @@ import { RequestSpellingMetadata, TypeShape, WrapperReference, BehavioralSummary
 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 { RawCodeStructure, ExtractorOptions, TimingReport, ExtractionReport, CacheDiagnostic, DeclaredModule, KeptParses } from '@suss/extractor';
 
 /**
  * Loads the Python grammar into web-tree-sitter and parses a file.
@@ -415,6 +415,14 @@ interface PyClientResponse {
     body?: string[];
     /** Whether a refused request comes back as a response or raises where it was made. */
     failureDelivery?: "response" | "exception";
+    /** Whether the client follows a redirect itself or hands the 3xx back. */
+    redirectDelivery?: "followed" | "response";
+    /**
+     * The keyword argument one call passes to change `redirectDelivery`
+     * for itself: `allow_redirects` for requests, `follow_redirects` for
+     * httpx.
+     */
+    redirectOption?: RedirectOption;
 }
 /** An object a module exports that a route reads the request off. */
 interface RequestObject {
@@ -435,6 +443,13 @@ interface RouteConventions {
      * annotation says.
      */
     injectedParameterCallees?: string[];
+    /**
+     * Classes the library supplies a parameter for when the parameter is
+     * annotated with one, by dotted path, such as FastAPI's
+     * `fastapi.Request` and `fastapi.BackgroundTasks`. The client sends
+     * nothing for such a parameter either.
+     */
+    injectedParameterTypes?: string[];
     /**
      * What the library serves when a composed path has repeated slashes.
      * Werkzeug serves the merged path and redirects the written one, so Flask
@@ -476,6 +491,18 @@ interface RouteConventions {
     parameterAliasKeyword?: string;
     /** The ways the library runs a project's own function around a route. DESIGN.md lists what each one covers. */
     wrappers?: PyWrapperForm[];
+    /**
+     * The status the library itself responds with, before the handler runs,
+     * when a request input the route declares does not validate. FastAPI
+     * sends 422. Unset means the library checks nothing on its own.
+     */
+    validationFailureStatus?: number;
+    /**
+     * The number each of the library's status constants is, keyed by the
+     * module and name it is imported as (`fastapi.status.HTTP_404_NOT_FOUND`),
+     * for a project read without the library installed.
+     */
+    statusCodeConstants?: Record<string, number>;
 }
 /** The part of the request a parameter declared with one callable is read from. */
 interface ParameterSource {
@@ -582,6 +609,13 @@ interface DecoratedFunctionRoute extends RouteConventions {
     /** Unset leaves the return annotation as the only source for the response shape. */
     responseModelKeyword?: string;
     statusCodeKeyword?: string;
+    /**
+     * The keyword whose dictionary lists statuses a route may respond
+     * with, FastAPI's `responses`, on the route decorator, its router, a
+     * mount call above it or the app. Its keys become the route's declared
+     * statuses.
+     */
+    responsesKeyword?: string;
 }
 /**
  * The names a library gives the parts of router mounting, so a route's
@@ -805,6 +839,19 @@ interface RouterIndex {
      * built it, and every construction is already keyed by its call.
      */
     resolveConstruction(pattern: PythonDiscoveryPattern, module: ModuleBinding, constructorName: string, constructionKey: string): RoutePrefixResolution;
+    /**
+     * The mounts above the router built by this call, innermost first, up
+     * to the one on the app. Null unless every router on the way is mounted
+     * exactly once by a mount this reading followed, since a route reached
+     * two ways runs only the wrappers of the way a request took.
+     */
+    mountsAbove(pattern: PythonDiscoveryPattern, constructionKey: string): MountHop[] | null;
+}
+/** One mount above a router: the call that mounts it, and the router it mounts it on, null for the app. */
+interface MountHop {
+    call: Node;
+    file: string;
+    parentKey: string | null;
 }
 interface RouterIndexOptions extends ModuleResolverOptions {
     /** The project's facts, so a loop over a call can be settled by the rules. */
@@ -999,8 +1046,8 @@ interface ReachedFunction {
  *
  * A registration on the app reaches every route of the pack in the run,
  * because the run treats a pack's app as the only one. A registration on
- * a router reaches the routes decorated on that same router object, and
- * nothing mounted onto it.
+ * a router reaches its own routes, and with a mount call's own list it
+ * reaches those below it when each router on the way is mounted once.
  */
 
 interface WrapperIndexOptions {
@@ -1010,6 +1057,8 @@ interface WrapperIndexOptions {
     /** The function each function key was read from. */
     definitions: ReadonlyMap<string, Node>;
     storageFor: (file: BoundPythonFile) => StorageLookup | undefined;
+    /** Where each router is mounted, so a dependency registered on the way reaches the routes below it. */
+    routers?: RouterIndex;
 }
 /** The route asking which wrappers reach it: the decorator it was found by, and where that decorator was read. */
 interface RouteWrapperQuery {
@@ -1041,6 +1090,10 @@ declare class PythonWrapperIndex {
     /** By construction key: what a router or a blueprint registered. */
     private readonly ownRoutes;
     private readonly unitsByKey;
+    /** By pack name: the app constructions its routes run under. */
+    private readonly appCalls;
+    /** By wrapper reference: the parameters a dependency function declares, and its file. */
+    private readonly dependencyParameterTable;
     private readonly unitsByFile;
     /** Told about every registration, so a cache can repeat the ones a file's discovery made. */
     onRegistered: ((target: ReachedFunction, declared: FormOf) => void) | null;
@@ -1062,8 +1115,35 @@ declare class PythonWrapperIndex {
     }, target: ReachedFunction, declared: FormOf): void;
     /** The unit for a function, built once however many registrations point at it. */
     registered(target: ReachedFunction, declared: FormOf): Registered;
+    /**
+     * The parameters the dependencies among these wrappers declare, and
+     * whether one is declared through a parameter source such as `Query()`.
+     * The library fills those from the request and validates them, the same
+     * as parameters the route declares.
+     */
+    dependencyParameters(references: readonly WrapperReference[]): {
+        names: ReadonlySet<string>;
+        declaresSource: boolean;
+    };
     wrappersFor(query: RouteWrapperQuery): WrapperReference[];
+    /**
+     * What the mounts above the route's router register on the way down:
+     * the dependencies an `include_router` call lists, and those of each
+     * router it is mounted onto, outermost first, the order they run in.
+     */
+    private mountedAbove;
+    private registeredAbove;
     private ownRoutesOf;
+    /** The construction call of the router a route is decorated on, when a registrar reads it. */
+    private ownRouterOf;
+    /** Records the app a pack's routes run under, for the keywords written on its construction. */
+    recordApp(pack: string, call: Node, file: string): void;
+    /**
+     * Every call that registers something for a route on the way to it:
+     * the app's construction, the mount calls and the routers they mount
+     * onto, and the route's own router. A caller reads a keyword off each.
+     */
+    callsAbove(query: RouteWrapperQuery): Node[];
     /**
      * Where the decorator's object was built: the route's own file, the file
      * a project wrapper function is written in, or the file an imported

package/dist/index.d.ts

@@ -2,8 +2,8 @@ import { RequestSpellingMetadata, TypeShape, WrapperReference, BehavioralSummary
 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 { RawCodeStructure, ExtractorOptions, TimingReport, ExtractionReport, CacheDiagnostic, DeclaredModule, KeptParses } from '@suss/extractor';
 
 /**
  * Loads the Python grammar into web-tree-sitter and parses a file.
@@ -415,6 +415,14 @@ interface PyClientResponse {
     body?: string[];
     /** Whether a refused request comes back as a response or raises where it was made. */
     failureDelivery?: "response" | "exception";
+    /** Whether the client follows a redirect itself or hands the 3xx back. */
+    redirectDelivery?: "followed" | "response";
+    /**
+     * The keyword argument one call passes to change `redirectDelivery`
+     * for itself: `allow_redirects` for requests, `follow_redirects` for
+     * httpx.
+     */
+    redirectOption?: RedirectOption;
 }
 /** An object a module exports that a route reads the request off. */
 interface RequestObject {
@@ -435,6 +443,13 @@ interface RouteConventions {
      * annotation says.
      */
     injectedParameterCallees?: string[];
+    /**
+     * Classes the library supplies a parameter for when the parameter is
+     * annotated with one, by dotted path, such as FastAPI's
+     * `fastapi.Request` and `fastapi.BackgroundTasks`. The client sends
+     * nothing for such a parameter either.
+     */
+    injectedParameterTypes?: string[];
     /**
      * What the library serves when a composed path has repeated slashes.
      * Werkzeug serves the merged path and redirects the written one, so Flask
@@ -476,6 +491,18 @@ interface RouteConventions {
     parameterAliasKeyword?: string;
     /** The ways the library runs a project's own function around a route. DESIGN.md lists what each one covers. */
     wrappers?: PyWrapperForm[];
+    /**
+     * The status the library itself responds with, before the handler runs,
+     * when a request input the route declares does not validate. FastAPI
+     * sends 422. Unset means the library checks nothing on its own.
+     */
+    validationFailureStatus?: number;
+    /**
+     * The number each of the library's status constants is, keyed by the
+     * module and name it is imported as (`fastapi.status.HTTP_404_NOT_FOUND`),
+     * for a project read without the library installed.
+     */
+    statusCodeConstants?: Record<string, number>;
 }
 /** The part of the request a parameter declared with one callable is read from. */
 interface ParameterSource {
@@ -582,6 +609,13 @@ interface DecoratedFunctionRoute extends RouteConventions {
     /** Unset leaves the return annotation as the only source for the response shape. */
     responseModelKeyword?: string;
     statusCodeKeyword?: string;
+    /**
+     * The keyword whose dictionary lists statuses a route may respond
+     * with, FastAPI's `responses`, on the route decorator, its router, a
+     * mount call above it or the app. Its keys become the route's declared
+     * statuses.
+     */
+    responsesKeyword?: string;
 }
 /**
  * The names a library gives the parts of router mounting, so a route's
@@ -805,6 +839,19 @@ interface RouterIndex {
      * built it, and every construction is already keyed by its call.
      */
     resolveConstruction(pattern: PythonDiscoveryPattern, module: ModuleBinding, constructorName: string, constructionKey: string): RoutePrefixResolution;
+    /**
+     * The mounts above the router built by this call, innermost first, up
+     * to the one on the app. Null unless every router on the way is mounted
+     * exactly once by a mount this reading followed, since a route reached
+     * two ways runs only the wrappers of the way a request took.
+     */
+    mountsAbove(pattern: PythonDiscoveryPattern, constructionKey: string): MountHop[] | null;
+}
+/** One mount above a router: the call that mounts it, and the router it mounts it on, null for the app. */
+interface MountHop {
+    call: Node;
+    file: string;
+    parentKey: string | null;
 }
 interface RouterIndexOptions extends ModuleResolverOptions {
     /** The project's facts, so a loop over a call can be settled by the rules. */
@@ -999,8 +1046,8 @@ interface ReachedFunction {
  *
  * A registration on the app reaches every route of the pack in the run,
  * because the run treats a pack's app as the only one. A registration on
- * a router reaches the routes decorated on that same router object, and
- * nothing mounted onto it.
+ * a router reaches its own routes, and with a mount call's own list it
+ * reaches those below it when each router on the way is mounted once.
  */
 
 interface WrapperIndexOptions {
@@ -1010,6 +1057,8 @@ interface WrapperIndexOptions {
     /** The function each function key was read from. */
     definitions: ReadonlyMap<string, Node>;
     storageFor: (file: BoundPythonFile) => StorageLookup | undefined;
+    /** Where each router is mounted, so a dependency registered on the way reaches the routes below it. */
+    routers?: RouterIndex;
 }
 /** The route asking which wrappers reach it: the decorator it was found by, and where that decorator was read. */
 interface RouteWrapperQuery {
@@ -1041,6 +1090,10 @@ declare class PythonWrapperIndex {
     /** By construction key: what a router or a blueprint registered. */
     private readonly ownRoutes;
     private readonly unitsByKey;
+    /** By pack name: the app constructions its routes run under. */
+    private readonly appCalls;
+    /** By wrapper reference: the parameters a dependency function declares, and its file. */
+    private readonly dependencyParameterTable;
     private readonly unitsByFile;
     /** Told about every registration, so a cache can repeat the ones a file's discovery made. */
     onRegistered: ((target: ReachedFunction, declared: FormOf) => void) | null;
@@ -1062,8 +1115,35 @@ declare class PythonWrapperIndex {
     }, target: ReachedFunction, declared: FormOf): void;
     /** The unit for a function, built once however many registrations point at it. */
     registered(target: ReachedFunction, declared: FormOf): Registered;
+    /**
+     * The parameters the dependencies among these wrappers declare, and
+     * whether one is declared through a parameter source such as `Query()`.
+     * The library fills those from the request and validates them, the same
+     * as parameters the route declares.
+     */
+    dependencyParameters(references: readonly WrapperReference[]): {
+        names: ReadonlySet<string>;
+        declaresSource: boolean;
+    };
     wrappersFor(query: RouteWrapperQuery): WrapperReference[];
+    /**
+     * What the mounts above the route's router register on the way down:
+     * the dependencies an `include_router` call lists, and those of each
+     * router it is mounted onto, outermost first, the order they run in.
+     */
+    private mountedAbove;
+    private registeredAbove;
     private ownRoutesOf;
+    /** The construction call of the router a route is decorated on, when a registrar reads it. */
+    private ownRouterOf;
+    /** Records the app a pack's routes run under, for the keywords written on its construction. */
+    recordApp(pack: string, call: Node, file: string): void;
+    /**
+     * Every call that registers something for a route on the way to it:
+     * the app's construction, the mount calls and the routers they mount
+     * onto, and the route's own router. A caller reads a keyword off each.
+     */
+    callsAbove(query: RouteWrapperQuery): Node[];
     /**
      * Where the decorator's object was built: the route's own file, the file
      * a project wrapper function is written in, or the file an imported