fastapi-voyager 0.4.1__py3-none-any.whl

fastapi_voyager/type_helper.py

@@ -0,0 +1,232 @@
+import inspect
+import os
+from pydantic import BaseModel
+from typing import get_origin, get_args, Union, Annotated, Any
+from fastapi_voyager.type import FieldInfo
+from types import UnionType
+
+# Python <3.12 compatibility: TypeAliasType exists only from 3.12 (PEP 695)
+try:  # pragma: no cover - import guard
+    from typing import TypeAliasType  # type: ignore
+except Exception:  # pragma: no cover
+    class _DummyTypeAliasType:  # minimal sentinel so isinstance checks are safe
+        pass
+    TypeAliasType = _DummyTypeAliasType  # type: ignore
+
+
+def _is_optional(annotation):
+    origin = get_origin(annotation)
+    args = get_args(annotation)
+    if origin is Union and type(None) in args:
+        return True
+    return False
+
+
+def _is_list(annotation):
+    return getattr(annotation, "__origin__", None) == list
+
+
+def shelling_type(type):
+    while _is_optional(type) or _is_list(type):
+        type = type.__args__[0]
+    return type
+
+
+def full_class_name(cls):
+    return f"{cls.__module__}.{cls.__qualname__}"
+
+
+def get_core_types(tp):
+    """
+    - get the core type
+    - always return a tuple of core types
+    """
+    if tp is type(None):
+        return tuple()
+
+    # Unwrap PEP 695 type aliases (they wrap the actual annotation in __value__)
+    # Repeat in case of nested aliasing.
+    def _unwrap_alias(t):
+        while isinstance(t, TypeAliasType) or (
+            t.__class__.__name__ == 'TypeAliasType' and hasattr(t, '__value__')
+        ):
+            try:
+                t = t.__value__
+            except Exception:  # pragma: no cover - defensive
+                break
+        return t
+
+    tp = _unwrap_alias(tp)
+
+    # 1. Unwrap list layers
+    def _shell_list(_tp):
+        while _is_list(_tp):
+            args = getattr(_tp, "__args__", ())
+            if args:
+                _tp = args[0]
+            else:
+                break
+        return _tp
+    
+    tp = _shell_list(tp)
+
+    # Alias could wrap a list element, unwrap again
+    tp = _unwrap_alias(tp)
+
+    if tp is type(None): # check again
+        return tuple()
+
+    while True:
+        orig = get_origin(tp)
+
+        if orig in (Union, UnionType):
+            args = list(get_args(tp))
+            non_none = [a for a in args if a is not type(None)]  # noqa: E721
+            has_none = len(non_none) != len(args)
+            # Optional[T] case -> keep unwrapping (exactly one real type + None)
+            if has_none and len(non_none) == 1:
+                tp = non_none[0]
+                tp = _unwrap_alias(tp)
+                tp = _shell_list(tp)
+                continue
+            # General union: return all non-None members (order preserved)
+            if non_none:
+                return tuple(non_none)
+            return tuple()
+        break
+
+    # single concrete type
+    return (tp,)
+
+
+def get_type_name(anno):
+    def name_of(tp):
+        origin = get_origin(tp)
+        args = get_args(tp)
+
+        # Annotated[T, ...] -> T
+        if origin is Annotated:
+            return name_of(args[0]) if args else 'Annotated'
+
+        # Union / Optional
+        if origin is Union:
+            non_none = [a for a in args if a is not type(None)]
+            if len(non_none) == 1 and len(args) == 2:
+                return f"Optional[{name_of(non_none[0])}]"
+            return f"Union[{', '.join(name_of(a) for a in args)}]"
+
+        # Parametrized generics
+        if origin is not None:
+            origin_name_map = {
+                list: 'List',
+                dict: 'Dict',
+                set: 'Set',
+                tuple: 'Tuple',
+                frozenset: 'FrozenSet',
+            }
+            origin_name = origin_name_map.get(origin)
+            if origin_name is None:
+                origin_name = getattr(origin, '__name__', None) or str(origin).replace('typing.', '')
+            if args:
+                return f"{origin_name}[{', '.join(name_of(a) for a in args)}]"
+            return origin_name
+
+        # Non-generic leaf types
+        if tp is Any:
+            return 'Any'
+        if tp is None or tp is type(None):
+            return 'None'
+        if isinstance(tp, type):
+            return tp.__name__
+
+        # ForwardRef
+        fwd = getattr(tp, '__forward_arg__', None) or getattr(tp, 'arg', None)
+        if fwd:
+            return str(fwd)
+
+        # Fallback clean string
+        return str(tp).replace('typing.', '').replace('<class ', '').replace('>', '').replace("'", '')
+
+    return name_of(anno)
+
+def is_inheritance_of_pydantic_base(cls):
+        return issubclass(cls, BaseModel) and cls is not BaseModel
+
+
+def get_bases_fields(schemas: list[type[BaseModel]]) -> set[str]:
+    """Collect field names from a list of BaseModel subclasses (their model_fields keys)."""
+    fields: set[str] = set()
+    for schema in schemas:
+        for k, _ in getattr(schema, 'model_fields', {}).items():
+            fields.add(k)
+    return fields
+
+
+def get_pydantic_fields(schema: type[BaseModel], bases_fields: set[str]) -> list[FieldInfo]:
+    """Extract pydantic model fields with metadata.
+
+    Parameters:
+        schema: The pydantic BaseModel subclass to inspect.
+        bases_fields: Set of field names that come from base classes (for from_base marking).
+
+    Returns:
+        A list of FieldInfo objects describing the schema's direct fields.
+    """
+
+    def _is_object(anno):  # internal helper, previously a method on Analytics
+        _types = get_core_types(anno)
+        return any(is_inheritance_of_pydantic_base(t) for t in _types if t)
+
+    fields: list[FieldInfo] = []
+    for k, v in schema.model_fields.items():
+        anno = v.annotation
+        fields.append(FieldInfo(
+            is_object=_is_object(anno),
+            name=k,
+            from_base=k in bases_fields,
+            type_name=get_type_name(anno),
+            is_exclude=bool(v.exclude)
+        ))
+    return fields
+
+
+def get_vscode_link(kls):
+    """Build a VSCode deep link to the class definition.
+
+    Priority:
+      1. If running inside WSL and WSL_DISTRO_NAME is present, return a remote link:
+         vscode://vscode-remote/wsl+<distro>/<absolute/path>:<line>
+         (This opens directly in the VSCode WSL remote window.)
+      2. Else, if path is /mnt/<drive>/..., translate to Windows drive and return vscode://file/C:\\...:line
+      3. Else, fallback to vscode://file/<unix-absolute-path>:line
+    """
+    try:
+        source_file = inspect.getfile(kls)
+        _lines, start_line = inspect.getsourcelines(kls)
+
+        distro = os.environ.get("WSL_DISTRO_NAME")
+        if distro:
+            # Ensure absolute path (it should already be under /) and build remote link
+            return f"vscode://vscode-remote/wsl+{distro}{source_file}:{start_line}"
+
+        # Non-remote scenario: maybe user wants to open via translated Windows path
+        if source_file.startswith('/mnt/') and len(source_file) > 6:
+            parts = source_file.split('/')
+            if len(parts) >= 4 and len(parts[2]) == 1:  # drive letter
+                drive = parts[2].upper()
+                rest = parts[3:]
+                win_path = drive + ':\\' + '\\'.join(rest)
+                return f"vscode://file/{win_path}:{start_line}"
+
+        # Fallback plain unix path
+        return f"vscode://file/{source_file}:{start_line}"
+    except Exception:
+        return ""
+
+
+def get_source(kls):
+    try:
+        source = inspect.getsource(kls)
+        return source
+    except Exception:
+        return "failed to get source"

fastapi_voyager/version.py

@@ -0,0 +1,2 @@
+__all__ = ["__version__"]
+__version__ = "0.4.1"

fastapi_voyager/web/component/route-code-display.js

@@ -0,0 +1,73 @@
+const { defineComponent, ref, watch, onMounted } = window.Vue;
+
+// Component: RouteCodeDisplay
+// Props:
+//   routeId: route id key in routeItems
+//   modelValue: dialog visibility
+//   routes: object map { id: { id, name, source_code } }
+export default defineComponent({
+  name: 'RouteCodeDisplay',
+  props: {
+    routeId: { type: String, required: true },
+    modelValue: { type: Boolean, default: false },
+    routes: { type: Object, default: () => ({}) },
+  },
+  emits: ['close'],
+  setup(props, { emit }) {
+    const code = ref('');
+    const error = ref(null);
+    const link = ref('');
+
+    function close() { emit('close'); }
+
+    function highlightLater() {
+      requestAnimationFrame(() => {
+        try {
+          if (window.hljs) {
+            const block = document.querySelector('.frv-route-code-display pre code.language-python');
+            if (block) {
+              window.hljs.highlightElement(block);
+            }
+          }
+        } catch (e) {
+          console.warn('highlight failed', e);
+        }
+      });
+    }
+
+    function load() {
+      error.value = null;
+      if (!props.routeId) { code.value=''; return; }
+      const item = props.routes[props.routeId];
+      if (item && item.source_code) {
+        code.value = item.source_code;
+        link.value = item.vscode_link || '';
+        highlightLater();
+      } else if (item) {
+        code.value = '// no source code available';
+        link.value = item.vscode_link || '';
+      } else {
+        error.value = 'Route not found';
+        link.value = '';
+      }
+    }
+
+    watch(() => props.modelValue, (v) => { if (v) load(); });
+    watch(() => props.routeId, () => { if (props.modelValue) load(); });
+
+    onMounted(() => { if (props.modelValue) load(); });
+
+    return { code, error, close, link };
+  },
+  template: `
+  <div class="frv-route-code-display" style="border:1px solid #ccc; position:relative; width:50vw; max-width:50vw; height:100%; background:#fff;">
+    <q-btn dense flat round icon="close" @click="close" aria-label="Close" style="position:absolute; top:6px; right:6px; z-index:10; background:rgba(255,255,255,0.85)" />
+    <div v-if="link" class="q-ml-md q-mt-md" style="padding-top:4px;">
+      <a :href="link" target="_blank" rel="noopener" style="font-size:12px; color:#3b82f6;">Open in VSCode</a>
+    </div>
+    <div style="padding:40px 16px 16px 16px; height:100%; box-sizing:border-box; overflow:auto;">
+      <div v-if="error" style="color:#c10015; font-family:Menlo, monospace; font-size:12px;">{{ error }}</div>
+      <pre v-else style="margin:0;"><code class="language-python">{{ code }}</code></pre>
+    </div>
+  </div>`
+});

fastapi_voyager/web/component/schema-code-display.js

@@ -0,0 +1,152 @@
+const { defineComponent, ref, watch, onMounted } = window.Vue;
+
+// Component: SchemaCodeDisplay
+// Props:
+//   schemaName: full qualified schema id (module.Class)
+//   modelValue: boolean (dialog visibility from parent)
+//   source: optional direct source code (if already resolved client side)
+//   schemas: list of schema meta objects (each containing fullname & source_code)
+// Behavior:
+//   - When dialog opens and schemaName changes, search schemas prop and display its source_code.
+//   - No network / global cache side effects.
+export default defineComponent({
+  name: "SchemaCodeDisplay",
+  props: {
+    schemaName: { type: String, required: true },
+    modelValue: { type: Boolean, default: false },
+    source: { type: String, default: null },
+    schemas: { type: Array, default: () => [] },
+  },
+  emits: ["close"],
+  setup(props, { emit }) {
+    const loading = ref(false);
+    const code = ref("");
+    const link = ref("");
+    const error = ref(null);
+    const fields = ref([]); // schema fields list
+    const tab = ref('source');
+
+    function close() {
+      emit("close");
+    }
+
+    function highlightLater() {
+      // wait a tick for DOM update
+      requestAnimationFrame(() => {
+        try {
+          if (window.hljs) {
+            const block = document.querySelector(
+              ".frv-code-display pre code.language-python"
+            );
+            if (block) {
+              window.hljs.highlightElement(block);
+            }
+          }
+        } catch (e) {
+          console.warn("highlight failed", e);
+        }
+      });
+    }
+
+    function loadSource() {
+      if (!props.schemaName) return;
+      if (props.source) {
+        code.value = props.source;
+        highlightLater();
+        return;
+      }
+      loading.value = true;
+      error.value = null;
+      try {
+        const item = props.schemas.find((s) => s.fullname === props.schemaName);
+        if (item) {
+          link.value = item.vscode_link || "";
+          code.value = item.source_code || "// no source code available";
+          // capture fields if provided
+          fields.value = Array.isArray(item.fields) ? item.fields : [];
+          highlightLater();
+        } else {
+          error.value = "Schema not found";
+        }
+      } catch (e) {
+        error.value = "Failed to load source";
+      } finally {
+        loading.value = false;
+      }
+    }
+
+    // re-highlight when switching back to source tab
+    watch(
+      () => tab.value,
+      (val) => {
+        if (val === 'source') {
+          highlightLater();
+        }
+      }
+    );
+
+    watch(
+      () => props.modelValue,
+      (val) => {
+        if (val) {
+          loadSource();
+        }
+      }
+    );
+
+    onMounted(() => {
+      if (props.modelValue) loadSource();
+    });
+
+    return { loading, link, code, error, close, fields, tab };
+  },
+  template: `
+  <div class="frv-code-display" style="border: 1px solid #ccc; border-left: none; position:relative; width:40vw; max-width:40vw; height:100%; background:#fff;">
+			<q-btn dense flat round icon="close" @click="close" aria-label="Close"
+				style="position:absolute; top:6px; right:6px; z-index:10; background:rgba(255,255,255,0.85)" />
+      <div v-if="link" class="q-ml-md q-mt-md">
+        <a :href="link" target="_blank" rel="noopener" style="font-size:12px; color:#3b82f6;">
+          Open in VSCode
+        </a>
+      </div>
+
+      <div style="padding:8px 12px 0 12px; box-sizing:border-box;">
+        <q-tabs v-model="tab" align="left" dense active-color="primary" indicator-color="primary" class="text-grey-8">
+          <q-tab name="source" label="Source Code" />
+          <q-tab name="fields" label="Fields" />
+        </q-tabs>
+      </div>
+      <q-separator />
+      <div style="padding:8px 16px 16px 16px; height:75%; box-sizing:border-box; overflow:auto;">
+        <div v-if="loading" style="font-family:Menlo, monospace; font-size:12px;">Loading source...</div>
+        <div v-else-if="error" style="color:#c10015; font-family:Menlo, monospace; font-size:12px;">{{ error }}</div>
+        <template v-else>
+          <div v-show="tab === 'source'">
+            <pre style="margin:0;"><code class="language-python">{{ code }}</code></pre>
+          </div>
+          <div v-show="tab === 'fields'">
+            <table style="border-collapse:collapse; width:100%; font-size:12px; font-family:Menlo, monospace;">
+              <thead>
+                <tr>
+                  <th style="text-align:left; border-bottom:1px solid #ddd; padding:4px 6px;">Field</th>
+                  <th style="text-align:left; border-bottom:1px solid #ddd; padding:4px 6px;">Type</th>
+                  <th style="text-align:left; border-bottom:1px solid #ddd; padding:4px 6px;">From Base</th>
+                </tr>
+              </thead>
+              <tbody>
+                <tr v-for="f in fields" :key="f.name">
+                  <td style="padding:4px 6px; border-bottom:1px solid #f0f0f0;">{{ f.name }}</td>
+                  <td style="padding:4px 6px; border-bottom:1px solid #f0f0f0; white-space:nowrap;">{{ f.type_name }}</td>
+                  <td style="padding:4px 6px; border-bottom:1px solid #f0f0f0; text-align:left;">{{ f.from_base ? '✔︎' : '' }}</td>
+                </tr>
+                <tr v-if="!fields.length">
+                  <td colspan="3" style="padding:8px 6px; color:#666; font-style:italic;">No fields</td>
+                </tr>
+              </tbody>
+            </table>
+          </div>
+        </template>
+      </div>
+	</div>
+	`,
+});

fastapi_voyager/web/component/schema-field-filter.js

@@ -0,0 +1,189 @@
+import { GraphUI } from "../graph-ui.js";
+const { defineComponent, reactive, ref, onMounted, nextTick, watch } =
+  window.Vue;
+
+// SchemaFieldFilter component
+// Features:
+//  - Fetch initial schemas list (GET /dot) and build schema options
+//  - Second selector lists fields of the chosen schema
+//  - Query button disabled until a schema is selected
+//  - On query: POST /dot with schema_name + optional schema_field; render returned DOT in #graph-schema-field
+//  - Uses GraphUI once and re-renders
+//  - Emits 'queried' event after successful render (payload: { schemaName, fieldName })
+export default defineComponent({
+  name: "SchemaFieldFilter",
+  props: {
+    schemaName: { type: String, default: null }, // external injection triggers auto-query
+    schemas: { type: Array, default: () => [] }, // externally provided schemas (state.rawSchemasFull or similar)
+  },
+  emits: ["queried", "close"],
+  setup(props, { emit }) {
+    const state = reactive({
+      loadingSchemas: false,
+      querying: false,
+      schemas: [], // [{ name, fullname, fields: [{name,...}] }]
+      schemaOptions: [], // [{ label, value }]
+      fieldOptions: [], // [ field.name ]
+      schemaFullname: null,
+      fieldName: null,
+      error: null,
+      showFields: "object",
+      showFieldOptions: [
+        { label: "No fields", value: "single" },
+        { label: "Object fields", value: "object" },
+        { label: "All fields", value: "all" },
+      ],
+    });
+
+    let graphInstance = null;
+    let lastAppliedExternal = null;
+
+    async function loadSchemas() {
+      // Refactored: use externally provided props.schemas directly; no network call.
+      state.error = null;
+      state.schemas = Array.isArray(props.schemas) ? props.schemas : [];
+      state.schemaOptions = state.schemas.map((s) => ({
+        label: `${s.name} (${s.fullname})`,
+        value: s.fullname,
+      }));
+      // Maintain compatibility: loadingSchemas flag toggled quickly (no async work)
+      state.loadingSchemas = false;
+    }
+
+    function onFilterSchemas(val, update) {
+      const needle = (val || "").toLowerCase();
+      update(() => {
+        let opts = state.schemas.map((s) => ({
+          label: `${s.name} (${s.fullname})`,
+          value: s.fullname,
+        }));
+        if (needle) {
+          opts = opts.filter((o) => o.label.toLowerCase().includes(needle));
+        }
+        state.schemaOptions = opts;
+      });
+    }
+
+    function onSchemaChange(val) {
+      state.schemaFullname = val;
+      state.fieldName = null;
+      const schema = state.schemas.find((s) => s.fullname === val);
+      state.fieldOptions = schema ? schema.fields.map((f) => f.name) : [];
+    }
+
+    async function onQuery() {
+      if (!state.schemaFullname) return;
+      state.querying = true;
+      state.error = null;
+      try {
+        const payload = {
+          schema_name: state.schemaFullname,
+          schema_field: state.fieldName || null,
+          show_fields: state.showFields,
+        };
+        const res = await fetch("/dot", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(payload),
+        });
+        const dotText = await res.text();
+        if (!graphInstance) {
+          graphInstance = new GraphUI("#graph-schema-field");
+        }
+        await graphInstance.render(dotText);
+        emit("queried", {
+          schemaName: state.schemaFullname,
+          fieldName: state.fieldName,
+        });
+      } catch (e) {
+        state.error = "Query failed";
+        console.error("SchemaFieldFilter query failed", e);
+      } finally {
+        state.querying = false;
+      }
+    }
+
+    function applyExternalSchema(name) {
+      if (!name || !state.schemas.length) return;
+      if (lastAppliedExternal === name) return; // avoid duplicate
+      const schema = state.schemas.find((s) => s.fullname === name);
+      if (!schema) return;
+      state.schemaFullname = schema.fullname;
+      state.fieldOptions = schema.fields.map((f) => f.name);
+      state.fieldName = null; // reset field for external injection
+      lastAppliedExternal = name;
+      // auto query
+      onQuery();
+    }
+
+    onMounted(async () => {
+      await nextTick();
+      await loadSchemas();
+      if (props.schemaName) {
+        applyExternalSchema(props.schemaName);
+      }
+    });
+
+
+    function close() {
+      emit("close");
+    }
+
+    return { state, onSchemaChange, onQuery, close, onFilterSchemas };
+  },
+  template: `
+	<div style="height:100%; position:relative; background:#fff;">
+				<div style="position:absolute; top:8px; left:8px; z-index:10; background:rgba(255,255,255,0.95); padding:8px 10px; border-radius:4px; box-shadow:0 1px 3px rgba(0,0,0,0.15);" class="q-gutter-sm row items-center">
+			<q-select 
+				dense outlined use-input input-debounce="0"
+				v-model="state.schemaFullname"
+				:options="state.schemaOptions"
+				option-label="label"
+				option-value="value"
+				emit-value 
+        map-options
+				:loading="state.loadingSchemas"
+				style="min-width:220px"
+				clearable
+				label="Select schema"
+				@update:model-value="onSchemaChange"
+        @filter="onFilterSchemas"
+			/>
+			<q-select 
+				dense outlined
+				v-model="state.fieldName"
+				:disable="!state.schemaFullname || state.fieldOptions.length===0"
+				:options="state.fieldOptions"
+				style="min-width:180px"
+				clearable
+				label="Select field (optional)"
+			/>
+					<q-option-group
+						v-model="state.showFields"
+						:options="state.showFieldOptions"
+						type="radio"
+						inline
+						dense
+						color="primary"
+						style="min-width:260px"
+					/>
+			<q-btn 
+          class="q-ml-md"
+          icon="search"
+				  label="Search" 
+          outline
+				:disable="!state.schemaFullname" 
+				:loading="state.querying" 
+				@click="onQuery" />
+		</div>
+				<q-btn
+					flat dense round icon="close"
+					aria-label="Close"
+					@click="close"
+					style="position:absolute; top:6px; right:6px; z-index:11; background:rgba(255,255,255,0.85);"
+				/>
+		<div v-if="state.error" style="position:absolute; top:52px; left:8px; z-index:10; color:#c10015; font-size:12px;">{{ state.error }}</div>
+		<div id="graph-schema-field" style="width:100%; height:100%; overflow:auto; background:#fafafa"></div>
+	</div>
+	`,
+});