isqx.mkdocs¤

def on_instance(
    self,
    *,
    node: ast.AST | ObjectNode,
    obj: Object,
    agent: Visitor | Inspector,
    **kwargs: Any,
) -> None:
    inject_citation_into_docstring(obj, agent)

    # collect strict parent-child relationships
    if (
        isinstance(obj, Attribute)
        and isinstance(obj.value, ExprSubscript)
        and isinstance(
            parent_expr := obj.value.left, (ExprName, ExprAttribute)
        )
    ):
        parent_path = parent_expr.canonical_path
        if parent_path.split(".", 1)[0] in ("typing", "typing_extensions"):
            # heuristic: we captured something invalid like Union[str, int]
            return
        self.possible_parent_maps[obj.canonical_path] = parent_path

def on_module_instance(
    self,
    *,
    node: ast.AST | ObjectNode,
    mod: Module,
    agent: Visitor | Inspector,
    **kwargs: Any,
) -> None:
    """Populate definitions from the current module being visited using
    runtime analysis, if it is matches the path under the configured
    definitions list.

    Note that if module `a` contains `FOO: Annotated[float, isqx.M] = 1.0`
    and module `b` contains `from a import FOO`, then `self.definitions`
    will contain both (which points to the same object):

    - `a.FOO`: Definition(value=1.0, annotated_metadata=M)
    - `b.FOO`: Definition(value=1.0, annotated_metadata=None)

    which is not ideal. When `griffe` visits `b`, `on_alias` will make sure
    the definition for `b.FOO` is removed.
    """
    if mod.path not in self.config.definitions:
        return
    module_rt = dynamic_import(mod.path)
    metadata = dict(module_attribute_metadata(module_rt))
    self.definitions |= {
        f"{mod.path}.{name}": Definition(obj, metadata.get(name))
        for name, obj in inspect.getmembers(module_rt)
        if isinstance(obj, _ARGS_DEFINITION)
    }

def on_alias_instance(
    self,
    *,
    node: ast.AST | ObjectNode,
    alias: Alias,
    agent: Visitor | Inspector,
    **kwargs: Any,
) -> None:
    target_path = _get_alias_definition_path(alias)
    if target_path is not None:
        _register_public_api_candidate(
            alias.path,
            target_path,
            alias_targets=self.alias_targets,
            public_api_candidates=self.public_api_candidates,
        )
    # todo: actually we probably shouldn't do this
    if alias.path in self.definitions:
        del self.definitions[alias.path]

def on_package(
    self, *, pkg: Module, loader: GriffeLoader, **kwargs: Any
) -> None:
    _collect_alias_candidates(
        pkg_path=pkg.path,
        modules_collection=loader.modules_collection,
        alias_targets=self.alias_targets,
        public_api_candidates=self.public_api_candidates,
    )
    logger.info(f"loaded {len(self.definitions)} definitions")
    path_resolver = _PathResolver(
        alias_targets=self.alias_targets,
        public_api_candidates=self.public_api_candidates,
    )
    public_definitions = _build_public_unit_paths(
        self.definitions,
        path_resolver,
    )
    unit_decls = build_unit_decl_table(
        {
            path: definition.value
            for path, definition in self.definitions.items()
            if isinstance(definition.value, _ARGS_EXPR)
        },
        public_definitions=public_definitions,
    )
    serialized_units = serialize_unit_decls(unit_decls=unit_decls)

    for defs_path in self.config.details:
        for path, item in _process_details_module(
            defs_path,
            loader,
            self.definitions,
            path_resolver,
            unit_decls,
        ):
            objects = self.objects.setdefault(path, QtyKindDetail())
            attr_target: Attribute = loader.modules_collection[path]
            isqx_extras = _get_or_init_isqx_extras(attr_target)
            isqx_extras["units"] = serialized_units

            if isinstance(item, WikidataDetail):
                objects.wikidata.append(item)
                isqx_extras["wikidata"].append(item)
            elif isinstance(item, SymbolDetail):
                objects.symbols.append(item)
                isqx_extras["symbols"].append(item)
            elif isinstance(item, EquationDetail):
                objects.equations.append(item)
                isqx_extras["details"].append(item)

    # set the parent (if found). would be nice for jinja to also show this
    # but we focus on the frontend vis for now.
    for child_path, parent_path in self.possible_parent_maps.items():
        if child_path in self.objects and parent_path in self.objects:
            child_object_detail = self.objects[child_path]
            child_object_detail.parent = parent_path

    for path, details in self.objects.items():
        if path not in self.definitions:
            continue
        definition = self.definitions[path]
        if not isinstance(v := definition.value, QtyKind):
            continue
        details.unit_si_coherent = serialize_unit_expr(
            v.unit_si_coherent,
            unit_decls=unit_decls,
        )
        if v.tags is not None:
            details.tags = tuple(str(t) for t in v.tags)  # str for now

def write_objects(self, output_dir: str | Path) -> Path:
    path_resolver = _PathResolver(
        alias_targets=self.alias_targets,
        public_api_candidates=self.public_api_candidates,
    )
    public_definitions = _build_public_unit_paths(
        self.definitions,
        path_resolver,
    )
    unit_decls = build_unit_decl_table(
        {
            path: definition.value
            for path, definition in self.definitions.items()
            if isinstance(definition.value, _ARGS_EXPR)
        },
        public_definitions=public_definitions,
    )
    constants_by_definition_path: dict[str, Quantity] = {}
    for path, definition in self.definitions.items():
        if not isinstance(definition.value, (LazyProduct, *_ARGS_NUMBER)):
            continue
        value = definition.value
        value_str = str(
            value.to_approx() if isinstance(value, LazyProduct) else value
        )
        meta = definition.annotated_metadata
        if meta is None or meta.unit is None:
            logger.warning(
                f"no unit found for {path} in annotated metadata"
            )
            continue  # dimensionless quantities should be annotated anyways
        constants_by_definition_path[path] = Quantity(
            value=value_str,
            unit=serialize_unit_expr(
                meta.unit,
                unit_decls=unit_decls,
            ),
        )

    qty_kinds = _remap_public_api_indexed_dict(
        self.objects,
        path_resolver=path_resolver,
        remap_value=lambda details: _remap_qty_kind_detail(
            details,
            path_resolver,
        ),
    )
    constants = _remap_public_api_indexed_dict(
        constants_by_definition_path,
        path_resolver=path_resolver,
        remap_value=lambda quantity: _remap_quantity(
            quantity,
            path_resolver,
        ),
    )
    units = serialize_unit_decls(unit_decls=unit_decls)

    json_path = Path(output_dir) / "objects.json"
    output_data = {
        "qtyKinds": {
            path: to_dict(details) for path, details in qty_kinds.items()
        },
        "constants": {
            path: to_dict(details) for path, details in constants.items()
        },
        "units": units,
    }
    json_path.parent.mkdir(parents=True, exist_ok=True)
    with open(json_path, "w", encoding="utf-8") as f:
        json.dump(output_data, f)
    logger.info(f"wrote objects to {json_path}")
    return json_path