feat: support custom root and update type stub (#154)

Author: M4rshe1

python/typst/__init__.pyi

@@ -108,6 +108,10 @@ class Compiler:
         format: Optional[OutputFormat] = None,
         ppi: Optional[float] = None,
         sys_inputs: Union[EllipsisType, None, Dict[str, str]] = ...,
+        pdf_standards: Optional[
+            Union[Literal["1.7", "a-2b", "a-3b"], List[Literal["1.7", "a-2b", "a-3b"]]]
+        ] = [],
+        root: Optional[PathLike] = None,
     ) -> Optional[Union[bytes, List[bytes]]]:
         """Compile a Typst project.
         Args:
@@ -121,6 +125,9 @@ class Compiler:
                 - Ellipsis (default): Keep existing sys_inputs from initialization or previous compile.
                 - None: Clear sys_inputs (equivalent to empty dictionary).
                 - Dict[str, str]: Use the provided dictionary as sys_inputs.
+            pdf_standards (Optional[Union[Literal["1.7", "a-2b", "a-3b"], List[Literal["1.7", "a-2b", "a-3b"]]]]):
+                One or more PDF standard profiles to apply when exporting.
+            root (Optional[PathLike]): Override the root path for this compilation.
         Returns:
             Optional[Union[bytes, List[bytes]]]: Return the compiled file as `bytes` if output is `None`.
         """
@@ -132,6 +139,10 @@ class Compiler:
         format: Optional[OutputFormat] = None,
         ppi: Optional[float] = None,
         sys_inputs: Union[EllipsisType, None, Dict[str, str]] = ...,
+        pdf_standards: Optional[
+            Union[Literal["1.7", "a-2b", "a-3b"], List[Literal["1.7", "a-2b", "a-3b"]]]
+        ] = [],
+        root: Optional[PathLike] = None,
     ) -> Tuple[Optional[Union[bytes, List[bytes]]], List[TypstWarning]]:
         """Compile a Typst project and return both result and warnings.
         Args:
@@ -145,6 +156,9 @@ class Compiler:
                 - Ellipsis (default): Keep existing sys_inputs from initialization or previous compile.
                 - None: Clear sys_inputs (equivalent to empty dictionary).
                 - Dict[str, str]: Use the provided dictionary as sys_inputs.
+            pdf_standards (Optional[Union[Literal["1.7", "a-2b", "a-3b"], List[Literal["1.7", "a-2b", "a-3b"]]]]):
+                One or more PDF standard profiles to apply when exporting.
+            root (Optional[PathLike]): Override the root path for this compilation.
         Returns:
             Tuple[Optional[Union[bytes, List[bytes]]], List[TypstWarning]]: Return a tuple of (compiled_data, warnings).
             The first element is the compiled file as `bytes` if output is `None`, otherwise `None`.
@@ -157,13 +171,15 @@ class Compiler:
         field: Optional[str] = None,
         one: bool = False,
         format: Optional[Literal["json", "yaml"]] = None,
+        root: Optional[PathLike] = None,
     ) -> str:
         """Query a Typst document.
         Args:
             selector (str): Typst selector like `<label>`.
             field (Optional[str], optional): Field to query.
             one (bool, optional): Query only one element.
             format (Optional[str]): Output format, `json` or `yaml`.
+            root (Optional[PathLike]): Override the root path for this query.
         Returns:
             str: Return the query result.
         """

src/lib.rs

@@ -350,6 +350,15 @@ pub struct Compiler {
 }
 
 impl Compiler {
+    fn apply_root(&mut self, root: Option<PathBuf>) -> PyResult<()> {
+        if let Some(root) = root {
+            self.world
+                .set_root(root)
+                .map_err(|msg| PyRuntimeError::new_err(msg.to_string()))?;
+        }
+        Ok(())
+    }
+
     fn apply_input(&mut self, input: Option<Input>) -> PyResult<()> {
         if let Some(input) = input {
             self.world
@@ -516,7 +525,7 @@ impl Compiler {
 
     /// Compile a typst file to PDF
     #[allow(clippy::too_many_arguments)]
-    #[pyo3(name = "compile", signature = (input = None, output = None, format = None, ppi = None, sys_inputs = SysInputsOption::Keep, pdf_standards = Vec::new()))]
+    #[pyo3(name = "compile", signature = (input = None, output = None, format = None, ppi = None, sys_inputs = SysInputsOption::Keep, pdf_standards = Vec::new(), root = None))]
     fn py_compile(
         &mut self,
         py: Python<'_>,
@@ -526,7 +535,9 @@ impl Compiler {
         ppi: Option<f32>,
         #[pyo3(from_py_with = extract_sys_inputs_option)] sys_inputs: SysInputsOption,
         #[pyo3(from_py_with = extract_pdf_standards)] pdf_standards: Vec<typst_pdf::PdfStandard>,
+        root: Option<PathBuf>,
     ) -> PyResult<Py<PyAny>> {
+        self.apply_root(root)?;
         self.apply_input(input)?;
         self.apply_sys_inputs(sys_inputs);
         if let Some(output) = output {
@@ -592,7 +603,7 @@ impl Compiler {
 
     /// Compile a typst file and return both result and warnings
     #[allow(clippy::too_many_arguments)]
-    #[pyo3(name = "compile_with_warnings", signature = (input = None, output = None, format = None, ppi = None, sys_inputs = SysInputsOption::Keep, pdf_standards = Vec::new()))]
+    #[pyo3(name = "compile_with_warnings", signature = (input = None, output = None, format = None, ppi = None, sys_inputs = SysInputsOption::Keep, pdf_standards = Vec::new(), root = None))]
     fn py_compile_with_warnings(
         &mut self,
         py: Python<'_>,
@@ -602,7 +613,9 @@ impl Compiler {
         ppi: Option<f32>,
         #[pyo3(from_py_with = extract_sys_inputs_option)] sys_inputs: SysInputsOption,
         #[pyo3(from_py_with = extract_pdf_standards)] pdf_standards: Vec<typst_pdf::PdfStandard>,
+        root: Option<PathBuf>,
     ) -> PyResult<Py<PyAny>> {
+        self.apply_root(root)?;
         self.apply_input(input)?;
         self.apply_sys_inputs(sys_inputs);
         let result = py
@@ -656,15 +669,17 @@ impl Compiler {
     }
 
     /// Query a typst document
-    #[pyo3(name = "query", signature = (selector, field = None, one = false, format = None))]
+    #[pyo3(name = "query", signature = (selector, field = None, one = false, format = None, root = None))]
     fn py_query(
         &mut self,
         py: Python<'_>,
         selector: &str,
         field: Option<&str>,
         one: bool,
         format: Option<&str>,
+        root: Option<PathBuf>,
     ) -> PyResult<Py<PyAny>> {
+        self.apply_root(root)?;
         py.detach(|| self.query(selector, field, one, format))
             .map(|s| PyString::new(py, &s).into())
     }
@@ -713,6 +728,7 @@ fn compile(
         ppi,
         SysInputsOption::Keep,
         pdf_standards,
+        None,
     )
 }
 
@@ -759,6 +775,7 @@ fn compile_with_warnings(
         ppi,
         SysInputsOption::Keep,
         pdf_standards,
+        None,
     )
 }
 
@@ -801,7 +818,7 @@ fn py_query(
         sys_inputs,
         package_path,
     )?;
-    compiler.py_query(py, selector, field, one, format)
+    compiler.py_query(py, selector, field, one, format, None)
 }
 
 /// Python binding to typst

src/world.rs

@@ -135,6 +135,15 @@ impl SystemWorld {
         &self.root
     }
 
+    /// Update the root path for the world.
+    pub fn set_root(&mut self, root: PathBuf) -> StrResult<()> {
+        self.root = root
+            .canonicalize()
+            .map_err(|err| format!("Failed to canonicalize root: {}", err))?;
+        self.reset();
+        Ok(())
+    }
+
     /// The current working directory.
     pub fn workdir(&self) -> &Path {
         self.workdir.as_deref().unwrap_or(Path::new("."))