@suss/adapter-python 0.34.0 → 0.35.0

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 {
@@ -1026,6 +1075,16 @@ interface Registered {
     reference: WrapperReference;
     form: PyWrapperForm;
 }
+/**
+ * The closure a project's decorator hands back, read with the route's
+ * pattern. It runs the route's function where it calls the decorator's
+ * parameter, `continuation`. No pack declares it, so it has no form.
+ */
+interface DecoratorClosure {
+    pack: PythonPack;
+    pattern: PythonDiscoveryPattern;
+    continuation: string;
+}
 /** A wrapper form with the pattern and pack that declare it. */
 interface FormOf {
     pack: PythonPack;
@@ -1041,9 +1100,16 @@ 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;
+    /**
+     * Told about every registration, a pack's form or a project decorator's
+     * closure, so a cache can repeat the ones a file's discovery made.
+     */
+    onRegistered: ((target: ReachedFunction, how: FormOf | DecoratorClosure) => void) | null;
     constructor(options: WrapperIndexOptions, filesByPath: ReadonlyMap<string, BoundPythonFile>);
     /**
      * The same lookup `wrappersFor` noted under `id`, made again over this
@@ -1062,8 +1128,62 @@ 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 unit for the closure a project's decorator hands back, built once
+     * however many routes the decorator is written on. Its name is what
+     * calling the decorator writes, since the decorator may have a summary
+     * of its own under its name.
+     */
+    registeredClosure(target: ReachedFunction, closure: DecoratorClosure): WrapperReference;
+    /**
+     * 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[];
+    /**
+     * The decorators written on the route's function below the one that
+     * registers it, outermost first. Each wraps the function the library
+     * calls. None has a summary: a library's has no body in the run, and a
+     * project's own is not composed into the route yet, so a project
+     * decorator goes by what calling it writes, `require_admin(fn)`, which
+     * no summary is named. The decorators the packs read, such as the
+     * route's own and the namespace's `@ns.doc`, are left out.
+     */
+    private decoratorLayers;
+    private decoratorLayer;
+    /**
+     * The layer a project's own decorator puts around the route. When it
+     * hands back a closure written inside it that returns what calling the
+     * function it was given returns, the closure is summarized and
+     * composed into the route. Any other decorator, including one whose
+     * closure keeps going after that call, goes by the same name with no
+     * summary behind it.
+     */
+    private projectDecoratorLayer;
+    /**
+     * 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
@@ -1309,7 +1429,7 @@ interface ExtractPythonOptions {
     onExtractionReport?: (report: ExtractionReport) => void;
     /** Called once with what the cache decided, for `suss extract --timing`. */
     onCacheDiagnostic?: (diagnostic: CacheDiagnostic) => void;
-    /** Absolute. `<projectRoot>/.suss/cache` by default; `null` turns it off. */
+    /** Absolute. `<projectRoot>/.suss/cache` by default, or under `SUSS_CACHE_DIR`; `null` turns it off. */
     cacheDir?: string | null;
     /** The modules the project lists in `suss.json`, with absolute paths. */
     modules?: readonly DeclaredModule[];

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 {
@@ -1026,6 +1075,16 @@ interface Registered {
     reference: WrapperReference;
     form: PyWrapperForm;
 }
+/**
+ * The closure a project's decorator hands back, read with the route's
+ * pattern. It runs the route's function where it calls the decorator's
+ * parameter, `continuation`. No pack declares it, so it has no form.
+ */
+interface DecoratorClosure {
+    pack: PythonPack;
+    pattern: PythonDiscoveryPattern;
+    continuation: string;
+}
 /** A wrapper form with the pattern and pack that declare it. */
 interface FormOf {
     pack: PythonPack;
@@ -1041,9 +1100,16 @@ 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;
+    /**
+     * Told about every registration, a pack's form or a project decorator's
+     * closure, so a cache can repeat the ones a file's discovery made.
+     */
+    onRegistered: ((target: ReachedFunction, how: FormOf | DecoratorClosure) => void) | null;
     constructor(options: WrapperIndexOptions, filesByPath: ReadonlyMap<string, BoundPythonFile>);
     /**
      * The same lookup `wrappersFor` noted under `id`, made again over this
@@ -1062,8 +1128,62 @@ 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 unit for the closure a project's decorator hands back, built once
+     * however many routes the decorator is written on. Its name is what
+     * calling the decorator writes, since the decorator may have a summary
+     * of its own under its name.
+     */
+    registeredClosure(target: ReachedFunction, closure: DecoratorClosure): WrapperReference;
+    /**
+     * 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[];
+    /**
+     * The decorators written on the route's function below the one that
+     * registers it, outermost first. Each wraps the function the library
+     * calls. None has a summary: a library's has no body in the run, and a
+     * project's own is not composed into the route yet, so a project
+     * decorator goes by what calling it writes, `require_admin(fn)`, which
+     * no summary is named. The decorators the packs read, such as the
+     * route's own and the namespace's `@ns.doc`, are left out.
+     */
+    private decoratorLayers;
+    private decoratorLayer;
+    /**
+     * The layer a project's own decorator puts around the route. When it
+     * hands back a closure written inside it that returns what calling the
+     * function it was given returns, the closure is summarized and
+     * composed into the route. Any other decorator, including one whose
+     * closure keeps going after that call, goes by the same name with no
+     * summary behind it.
+     */
+    private projectDecoratorLayer;
+    /**
+     * 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
@@ -1309,7 +1429,7 @@ interface ExtractPythonOptions {
     onExtractionReport?: (report: ExtractionReport) => void;
     /** Called once with what the cache decided, for `suss extract --timing`. */
     onCacheDiagnostic?: (diagnostic: CacheDiagnostic) => void;
-    /** Absolute. `<projectRoot>/.suss/cache` by default; `null` turns it off. */
+    /** Absolute. `<projectRoot>/.suss/cache` by default, or under `SUSS_CACHE_DIR`; `null` turns it off. */
     cacheDir?: string | null;
     /** The modules the project lists in `suss.json`, with absolute paths. */
     modules?: readonly DeclaredModule[];