ty_python_core/
program_file.rs

1use ruff_db::PythonFile;
2use ruff_db::files::File;
3use ruff_python_ast::PythonVersion;
4use ty_module_resolver::{ResolverEnvironment, ResolverFile};
5
6use crate::{Db, program::Program};
7
8/// A file interpreted within a particular Python program.
9///
10/// The same file can participate in multiple programs, each with different Python versions, search
11/// paths, or other settings that affect type inference.
12///
13/// For example:
14///
15/// ```text
16/// project/
17/// ├── app.py         # Project program: Python 3.11
18/// ├── generate.py    # Script program:  Python 3.12
19/// └── shared.py      # Imported by both
20/// ```
21///
22/// In `shared.py`, version-dependent code can produce different types:
23///
24/// ```python
25/// import sys
26///
27/// if sys.version_info >= (3, 12):
28///     value = 1
29/// else:
30///     value = "one"
31/// ```
32///
33/// The two interpretations therefore need separate semantic identities:
34///
35/// ```text
36/// ProgramFile(shared.py, project program) -> value: str
37/// ProgramFile(shared.py, script program)  -> value: int
38/// ```
39///
40/// Semantic queries, such as `semantic_index`, use `ProgramFile` to avoid sharing results between
41/// incompatible programs. Lower-level operations use narrower identities where possible:
42///
43/// ```text
44/// program_file.python_file(db)   -> File + Python version
45/// program_file.resolver_file(db) -> File + resolver environment
46/// ```
47///
48/// This allows programs with the same Python version to share parsed syntax, and programs with
49/// equivalent resolver environments to share module resolution, while keeping type inference
50/// isolated.
51#[salsa::interned(
52    debug,
53    constructor = new_internal,
54    heap_size = ruff_memory_usage::heap_size
55)]
56pub struct ProgramFile<'db> {
57    /// Cache the parser key even though its Python version is redundant with `program`:
58    /// program files are created infrequently, but their parser keys are looked up extensively.
59    #[returns(copy)]
60    pub python_file: PythonFile<'db>,
61
62    #[returns(copy)]
63    pub program: Program<'db>,
64}
65
66impl get_size2::GetSize for ProgramFile<'_> {}
67
68impl<'db> ProgramFile<'db> {
69    pub fn new(db: &'db dyn Db, file: File, program: Program<'db>) -> Self {
70        let python_file = PythonFile::new(db, file, program.python_version(db));
71        Self::new_internal(db, python_file, program)
72    }
73
74    /// Returns the physical file represented by this program file.
75    pub fn file(self, db: &'db dyn Db) -> File {
76        self.python_file(db).file(db)
77    }
78
79    /// Returns the module-resolution environment for this program file.
80    pub fn resolver_environment(self, db: &'db dyn Db) -> ResolverEnvironment<'db> {
81        self.program(db).resolver_environment(db)
82    }
83
84    /// Returns the resolver key for this file.
85    pub fn resolver_file(self, db: &'db dyn Db) -> ResolverFile<'db> {
86        ResolverFile::new(db, self.file(db), self.resolver_environment(db))
87    }
88
89    /// Returns the Python version associated with this file's program.
90    pub fn python_version(self, db: &'db dyn Db) -> PythonVersion {
91        self.program(db).python_version(db)
92    }
93}
ty_python_core/program_file.rs

ty_python_core/
program_file.rs
