@suss/adapter-python 0.34.1 → 0.35.0

package/dist/index.d.cts

@@ -1075,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;
@@ -1095,8 +1105,11 @@ declare class PythonWrapperIndex {
     /** 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
@@ -1115,6 +1128,13 @@ 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()`.
@@ -1126,6 +1146,26 @@ declare class PythonWrapperIndex {
         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
@@ -1389,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

@@ -1075,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;
@@ -1095,8 +1105,11 @@ declare class PythonWrapperIndex {
     /** 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
@@ -1115,6 +1128,13 @@ 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()`.
@@ -1126,6 +1146,26 @@ declare class PythonWrapperIndex {
         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
@@ -1389,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[];