/// The scope in which the definition occurs.

///

/// Storing the interned scope avoids retaining the file and file-local scope separately, at

/// the cost of database lookups when either of those values is needed.

#[returns(copy)]

pub scope_id: ScopeId<'db>,

/// The place ID and re-export state of the definition.

#[returns(copy)]

place_info: DefinitionPlace,

/// WARNING: Only access this field when doing type inference for the same

/// file as where `Definition` is defined to avoid cross-file query dependencies.

#[no_eq]

#[returns(ref)]

#[tracked]

pub kind: DefinitionKind<'db>,

pub(crate) fn new(

db: &'db dyn Db,

scope_id: ScopeId<'db>,

place: ScopedPlaceId,

kind: DefinitionKind<'db>,

is_reexported: bool,

) -> Self {

Self::new_internal(

db,

scope_id,

DefinitionPlace::new(place, is_reexported),

kind,

)

}

pub fn scope(self, db: &'db dyn Db) -> ScopeId<'db> {

self.scope_id(db)

}

pub fn file(self, db: &'db dyn Db) -> File {

self.scope_id(db).file(db)

}

pub fn python_file(self, db: &'db dyn Db) -> PythonFile<'db> {

self.scope_id(db).python_file(db)

}

pub fn program_file(self, db: &'db dyn Db) -> ProgramFile<'db> {

self.scope_id(db).program_file(db)

}

pub fn program(self, db: &'db dyn Db) -> Program<'db> {

self.scope_id(db).program(db)

}

pub fn file_scope(self, db: &'db dyn Db) -> FileScopeId {

self.scope_id(db).file_scope_id(db)

}

pub fn place(self, db: &'db dyn Db) -> ScopedPlaceId {

self.place_info(db).place()

}

pub fn is_reexported(self, db: &'db dyn Db) -> bool {

self.place_info(db).is_reexported()

}

pub fn full_range(self, db: &'db dyn Db, module: &ParsedModuleRef) -> FileRange {

FileRange::new(self.file(db), self.kind(db).full_range(module))

}

pub fn focus_range(self, db: &'db dyn Db, module: &ParsedModuleRef) -> FileRange {

FileRange::new(self.file(db), self.kind(db).target_range(module))

}

/// Returns the name of the item being defined, if applicable.

pub fn name(self, db: &'db dyn Db) -> Option<String> {

let module = parsed_module(db, self.python_file(db)).load(db);

let kind = self.kind(db);

match kind {

DefinitionKind::Function(def) => {

let node = def.node(&module);

Some(node.name.as_str().to_string())

}

DefinitionKind::Class(def) => {

let node = def.node(&module);

Some(node.name.as_str().to_string())

}

DefinitionKind::TypeAlias(def) => {

let node = def.node(&module);

Some(

node.name

.as_name_expr()

.expect("type alias name should be a NameExpr")

.id

.as_str()

.to_string(),

)

}

DefinitionKind::Assignment(assignment) => {

let target_node = assignment.target.node(&module);

target_node

.as_name_expr()

.map(|name_expr| name_expr.id.as_str().to_string())

}

_ => None,

}

}

/// Extract a docstring from this definition, if applicable.

/// This method returns a docstring for function, class, and attribute definitions.

/// The docstring is extracted from the first statement in the body if it's a string literal.

pub fn docstring(self, db: &'db dyn Db) -> Option<String> {

let module = parsed_module(db, self.python_file(db)).load(db);

let kind = self.kind(db);

match kind {

DefinitionKind::Assignment(assign_def) => {

let assign_node = assign_def.target(&module);

attribute_docstring(&module, assign_node)

.map(|docstring_expr| docstring_expr.value.to_str().to_owned())

}

DefinitionKind::AnnotatedAssignment(assign_def) => {

let assign_node = assign_def.target(&module);

attribute_docstring(&module, assign_node)

.map(|docstring_expr| docstring_expr.value.to_str().to_owned())

}

DefinitionKind::Function(function_def) => {

let function_node = function_def.node(&module);

docstring_from_body(&function_node.body)

.map(|docstring_expr| docstring_expr.value.to_str().to_owned())

}

DefinitionKind::Class(class_def) => {

let class_node = class_def.node(&module);

docstring_from_body(&class_node.body)

.map(|docstring_expr| docstring_expr.value.to_str().to_owned())

}

_ => None,

}

}

Symbol {

id: ScopedSymbolId,

is_reexported: bool,

},

Member {

id: ScopedMemberId,

is_reexported: bool,

},

fn new(place: ScopedPlaceId, is_reexported: bool) -> Self {

match place {

ScopedPlaceId::Symbol(id) => Self::Symbol { id, is_reexported },

ScopedPlaceId::Member(id) => Self::Member { id, is_reexported },

}

}

fn place(self) -> ScopedPlaceId {

match self {

Self::Symbol { id, .. } => ScopedPlaceId::Symbol(id),

Self::Member { id, .. } => ScopedPlaceId::Member(id),

}

}

fn is_reexported(self) -> bool {

match self {

Self::Symbol { is_reexported, .. } | Self::Member { is_reexported, .. } => {

is_reexported

}

}

}

let stmt = body.first()?;

// Require the docstring to be a standalone expression.

let ast::StmtExpr {

value,

range: _,

node_index: _,

} = stmt.as_expr_stmt()?;

// Only match string literals.

value.as_string_literal_expr()

module: &'a ParsedModuleRef,

assign_lvalue: &Expr,

) -> Option<&'a ast::ExprStringLiteral> {

// Find all the ancestors of the assign lvalue

let covering_node = covering_node(module.syntax().into(), assign_lvalue.range());

// The assignment is the closest parent statement

let assign = covering_node.find_first(AnyNodeRef::is_statement).ok()?;

let parent = assign.parent()?;

let assign_node = assign.node();

// The docs must be the next statement

let parent_body = suite(assign_node, parent)?;

let next_stmt = parent_body.next_sibling()?;

// Require the docstring to be a standalone expression.

let ast::Stmt::Expr(ast::StmtExpr {

value,

range: _,

node_index: _,

}) = next_stmt

else {

return None;

};

// Only match string literals.

value.as_string_literal_expr()

pub(crate) fn push(&mut self, definition: Definition<'db>) {

self.definitions.push(definition);

}

pub(crate) fn into_boxed_slice(self) -> Box<[Definition<'db>]> {

self.definitions.into_vec().into_boxed_slice()

}

type Target = [Definition<'db>];

fn deref(&self) -> &Self::Target {

&self.definitions

}

Defined(Definition<'db>),

/// Represents the implicit "unbound"/"undeclared" definition of every place.

Undefined,

/// Represents a definition that has been deleted.

/// This used when an attribute/subscript definition (such as `x.y = ...`, `x[0] = ...`) becomes obsolete due to a reassignment of the root place.

Deleted,

pub fn is_defined_and(self, f: impl Fn(Definition<'db>) -> bool) -> bool {

matches!(self, DefinitionState::Defined(def) if f(def))

}

pub fn is_undefined_or(self, f: impl Fn(Definition<'db>) -> bool) -> bool {

matches!(self, DefinitionState::Undefined)

|| matches!(self, DefinitionState::Defined(def) if f(def))

}

#[allow(unused)]

pub fn definition(self) -> Option<Definition<'db>> {

match self {

DefinitionState::Defined(def) => Some(def),

DefinitionState::Deleted | DefinitionState::Undefined => None,

}

}

Import(ImportDefinitionNodeRef<'ast>),

ImportFrom(ImportFromDefinitionNodeRef<'ast>),

ImportFromSubmodule(ImportFromSubmoduleDefinitionNodeRef<'ast>),

ImportStar(StarImportDefinitionNodeRef<'ast>),

For(ForStmtDefinitionNodeRef<'ast, 'db>),

Function(&'ast ast::StmtFunctionDef),

Class(&'ast ast::StmtClassDef),

TypeAlias(&'ast ast::StmtTypeAlias),

NamedExpression(&'ast ast::ExprNamed),

Assignment(AssignmentDefinitionNodeRef<'ast, 'db>),

AnnotatedAssignment(AnnotatedAssignmentDefinitionNodeRef<'ast>),

AugmentedAssignment(&'ast ast::StmtAugAssign),

DictKeyAssignment(DictKeyAssignmentNodeRef<'ast, 'db>),

Comprehension(ComprehensionDefinitionNodeRef<'ast, 'db>),

Parameter(ParameterDefinitionNodeRef<'ast>),

LambdaParameter(LambdaParameterDefinitionNodeRef<'ast>),

WithItem(WithItemDefinitionNodeRef<'ast, 'db>),

MatchPattern(MatchPatternDefinitionNodeRef<'ast, 'db>),

ExceptHandler(ExceptHandlerDefinitionNodeRef<'ast>),

TypeVar(&'ast ast::TypeParamTypeVar),

ParamSpec(&'ast ast::TypeParamParamSpec),

TypeVarTuple(&'ast ast::TypeParamTypeVarTuple),

LoopHeader(LoopHeaderDefinitionNodeRef<'ast>),

fn from(node: &'ast ast::StmtFunctionDef) -> Self {

Self::Function(node)

}

fn from(node: &'ast ast::StmtClassDef) -> Self {

Self::Class(node)

}

fn from(node: &'ast ast::StmtTypeAlias) -> Self {

Self::TypeAlias(node)

}

fn from(node: &'ast ast::ExprNamed) -> Self {

Self::NamedExpression(node)

}

fn from(node: &'ast ast::StmtAugAssign) -> Self {

Self::AugmentedAssignment(node)

}

fn from(value: &'ast ast::TypeParamTypeVar) -> Self {

Self::TypeVar(value)

}

fn from(value: &'ast ast::TypeParamParamSpec) -> Self {

Self::ParamSpec(value)

}

fn from(value: &'ast ast::TypeParamTypeVarTuple) -> Self {

Self::TypeVarTuple(value)

}

fn from(value: LoopHeaderDefinitionNodeRef<'ast>) -> Self {

Self::LoopHeader(value)

}

fn from(node_ref: ImportDefinitionNodeRef<'ast>) -> Self {

Self::Import(node_ref)

}

fn from(node_ref: ImportFromDefinitionNodeRef<'ast>) -> Self {

Self::ImportFrom(node_ref)

}

fn from(node_ref: ImportFromSubmoduleDefinitionNodeRef<'ast>) -> Self {

Self::ImportFromSubmodule(node_ref)

}

fn from(value: ForStmtDefinitionNodeRef<'ast, 'db>) -> Self {

Self::For(value)

}

fn from(node_ref: AssignmentDefinitionNodeRef<'ast, 'db>) -> Self {

Self::Assignment(node_ref)

}

fn from(node_ref: AnnotatedAssignmentDefinitionNodeRef<'ast>) -> Self {

Self::AnnotatedAssignment(node_ref)

}

fn from(node_ref: DictKeyAssignmentNodeRef<'ast, 'db>) -> Self {

Self::DictKeyAssignment(node_ref)

}

fn from(node_ref: WithItemDefinitionNodeRef<'ast, 'db>) -> Self {

Self::WithItem(node_ref)

}

fn from(node: ComprehensionDefinitionNodeRef<'ast, 'db>) -> Self {

Self::Comprehension(node)

}

fn from(node: ParameterDefinitionNodeRef<'ast>) -> Self {

Self::Parameter(node)

}

fn from(node: LambdaParameterDefinitionNodeRef<'ast>) -> Self {

Self::LambdaParameter(node)

}

fn from(node: MatchPatternDefinitionNodeRef<'ast, 'db>) -> Self {

Self::MatchPattern(node)

}

fn from(node: StarImportDefinitionNodeRef<'ast>) -> Self {

Self::ImportStar(node)

}

pub(crate) node: &'ast ast::StmtImport,

pub(crate) alias_index: usize,

pub(crate) is_reexported: bool,

pub(crate) node: &'ast ast::StmtImportFrom,

pub(crate) alias_index: usize,

pub(crate) is_reexported: bool,

pub(crate) unpack: Option<Unpack<'db>>,

pub(crate) value: &'ast ast::Expr,

pub(crate) target: &'ast ast::Expr,

pub(crate) owner: BindingsOwner,

pub(crate) key: &'ast ast::Expr,

pub(crate) value: &'ast ast::Expr,

pub(crate) assignment: Definition<'db>,

pub(crate) unpack: Option<(UnpackPosition, Unpack<'db>)>,

pub(crate) item: &'ast ast::WithItem,

pub(crate) target: &'ast ast::Expr,

pub(crate) is_async: bool,

pub(crate) unpack: Option<(UnpackPosition, Unpack<'db>)>,

pub(crate) node: &'ast ast::StmtFor,

pub(crate) target: &'ast ast::Expr,

pub(crate) loop_stmt: LoopStmtRef<'ast>,

pub(crate) place: ScopedPlaceId,

pub(crate) loop_header_id: LoopHeaderId,

pub(crate) unpack: Option<(UnpackPosition, Unpack<'db>)>,

pub(crate) node: &'ast ast::Comprehension,

pub(crate) target: &'ast ast::Expr,

pub(crate) first: bool,

VariadicPositionalParameter(&'ast ast::Parameter),

VariadicKeywordParameter(&'ast ast::Parameter),

Parameter(&'ast ast::ParameterWithDefault),

fn into_owned(self, parsed: &ParsedModuleRef) -> ParameterDefinitionNodeKind {

match self {

Self::VariadicPositionalParameter(parameter) => {

ParameterDefinitionNodeKind::VariadicPositionalParameter(AstNodeRef::new(

parsed, parameter,

))

}

Self::VariadicKeywordParameter(parameter) => {

ParameterDefinitionNodeKind::VariadicKeywordParameter(AstNodeRef::new(

parsed, parameter,

))

}

Self::Parameter(parameter) => {

ParameterDefinitionNodeKind::Parameter(AstNodeRef::new(parsed, parameter))

}

}

}

fn key(self) -> DefinitionNodeKey {

match self {

Self::VariadicPositionalParameter(node) => node.into(),

Self::VariadicKeywordParameter(node) => node.into(),

Self::Parameter(node) => (&node.parameter).into(),

}

}

pub(crate) index: usize,

pub(crate) parameter: ParameterDefinitionNodeRef<'ast>,

pub(crate) lambda: &'ast ast::ExprLambda,

/// The outermost pattern node in which the identifier being defined occurs.

pub(crate) pattern: &'ast ast::Pattern,

/// The identifier being defined.

pub(crate) identifier: &'ast ast::Identifier,

/// The predicate for the complete match case containing this binding.

pub(crate) predicate: PatternPredicate<'db>,

pub(super) fn into_owned(self, parsed: &ParsedModuleRef) -> DefinitionKind<'db> {

match self {

DefinitionNodeRef::Import(ImportDefinitionNodeRef {

node,

alias_index,

is_reexported,

}) => DefinitionKind::Import(ImportDefinitionKind {

node: AstNodeRef::new(parsed, node),

alias_index: alias_index

.try_into()

.expect("import alias index should fit in u32"),

is_reexported,

}),

DefinitionNodeRef::ImportFrom(ImportFromDefinitionNodeRef {

node,

alias_index,

is_reexported,

}) => DefinitionKind::ImportFrom(ImportFromDefinitionKind {

node: AstNodeRef::new(parsed, node),

alias_index: alias_index

.try_into()

.expect("import-from alias index should fit in u32"),

is_reexported,

}),

DefinitionNodeRef::ImportFromSubmodule(ImportFromSubmoduleDefinitionNodeRef {

node,

module_index,

}) => DefinitionKind::ImportFromSubmodule(ImportFromSubmoduleDefinitionKind {

node: AstNodeRef::new(parsed, node),

module_index: module_index

.try_into()

.expect("import-from submodule index should fit in u32"),

}),

DefinitionNodeRef::ImportStar(star_import) => {

let StarImportDefinitionNodeRef { node, symbol_id } = star_import;

DefinitionKind::StarImport(StarImportDefinitionKind {

node: AstNodeRef::new(parsed, node),

symbol_id,

})

}

DefinitionNodeRef::Function(function) => {

DefinitionKind::Function(AstNodeRef::new(parsed, function))

}

DefinitionNodeRef::Class(class) => {

DefinitionKind::Class(AstNodeRef::new(parsed, class))

}

DefinitionNodeRef::TypeAlias(type_alias) => {

DefinitionKind::TypeAlias(AstNodeRef::new(parsed, type_alias))

}

DefinitionNodeRef::NamedExpression(named) => {

DefinitionKind::NamedExpression(AstNodeRef::new(parsed, named))

}

DefinitionNodeRef::Assignment(AssignmentDefinitionNodeRef {

unpack,

value,

target,

owner,

}) => DefinitionKind::Assignment(AssignmentDefinitionKind {

unpack,

value: AstNodeRef::new(parsed, value),

target: AstNodeRef::new(parsed, target),

owner,

}),

DefinitionNodeRef::AnnotatedAssignment(AnnotatedAssignmentDefinitionNodeRef {

node,

}) => DefinitionKind::AnnotatedAssignment(AnnotatedAssignmentDefinitionKind {

node: AstNodeRef::new(parsed, node),

has_value: node.value.is_some(),

}),

DefinitionNodeRef::AugmentedAssignment(augmented_assignment) => {

DefinitionKind::AugmentedAssignment(AstNodeRef::new(parsed, augmented_assignment))

}

DefinitionNodeRef::DictKeyAssignment(DictKeyAssignmentNodeRef {

key,

value,