From 5c854fc6902177f81dc8bb662b36b713d67615ea Mon Sep 17 00:00:00 2001 From: Ashwin Naren Date: Thu, 3 Apr 2025 09:23:22 -0700 Subject: [PATCH] clear out warnings --- common/src/linked_list.rs | 2 +- src/lib.rs | 4 ++-- src/settings.rs | 4 ++++ src/shell.rs | 2 ++ stdlib/src/pystruct.rs | 4 ++-- vm/src/builtins/mod.rs | 4 ++-- vm/src/dict_inner.rs | 6 +++--- vm/src/function/builtin.rs | 2 +- vm/src/import.rs | 5 ++--- vm/src/lib.rs | 7 ++++--- vm/src/object/core.rs | 16 ++++++++-------- vm/src/object/traverse.rs | 6 +++--- vm/src/prelude.rs | 4 ++++ vm/src/protocol/buffer.rs | 2 +- vm/src/protocol/object.rs | 2 +- vm/src/readline.rs | 5 +++++ vm/src/suggestion.rs | 3 +++ vm/src/version.rs | 3 +-- vm/src/vm/interpreter.rs | 13 ++++++------- vm/src/vm/mod.rs | 4 ++-- vm/src/vm/vm_ops.rs | 4 ++-- wtf8/src/lib.rs | 2 +- 22 files changed, 60 insertions(+), 44 deletions(-) diff --git a/common/src/linked_list.rs b/common/src/linked_list.rs index 7f55d727f..83577b71d 100644 --- a/common/src/linked_list.rs +++ b/common/src/linked_list.rs @@ -1,4 +1,4 @@ -//! This module is modified from tokio::util::linked_list: https://github.com/tokio-rs/tokio/blob/master/tokio/src/util/linked_list.rs +//! This module is modified from tokio::util::linked_list: //! Tokio is licensed under the MIT license: //! //! Copyright (c) 2021 Tokio Contributors diff --git a/src/lib.rs b/src/lib.rs index e415d847c..98de3de5c 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,9 +1,9 @@ //! This is the `rustpython` binary. If you're looking to embed RustPython into your application, -//! you're likely looking for the [`rustpython-vm`](https://docs.rs/rustpython-vm) crate. +//! you're likely looking for the [`rustpython_vm`] crate. //! //! You can install `rustpython` with `cargo install rustpython`, or if you'd like to inject your //! own native modules you can make a binary crate that depends on the `rustpython` crate (and -//! probably `rustpython-vm`, too), and make a `main.rs` that looks like: +//! probably [`rustpython_vm`], too), and make a `main.rs` that looks like: //! //! ```no_run //! use rustpython_vm::{pymodule, py_freeze}; diff --git a/src/settings.rs b/src/settings.rs index 76c46ac43..00ee55bdd 100644 --- a/src/settings.rs +++ b/src/settings.rs @@ -13,7 +13,11 @@ pub enum RunMode { } pub enum InstallPipMode { + /// Install pip using the ensurepip pip module. This has a higher chance of + /// success, but may not install the latest version of pip. Ensurepip, + /// Install pip using the get-pip.py script, which retrieves the latest pip version. + /// This can be broken due to incompatibilities with cpython. GetPip, } diff --git a/src/shell.rs b/src/shell.rs index 98ee6eee2..04090a49f 100644 --- a/src/shell.rs +++ b/src/shell.rs @@ -71,6 +71,8 @@ fn shell_exec( } } + +/// Enter a repl loop pub fn run_shell(vm: &VirtualMachine, scope: Scope) -> PyResult<()> { let mut repl = Readline::new(helper::ShellHelper::new(vm, scope.globals.clone())); let mut full_input = String::new(); diff --git a/stdlib/src/pystruct.rs b/stdlib/src/pystruct.rs index 220970dd2..942647091 100644 --- a/stdlib/src/pystruct.rs +++ b/stdlib/src/pystruct.rs @@ -1,9 +1,9 @@ //! Python struct module. //! -//! Docs: https://docs.python.org/3/library/struct.html +//! Docs: //! //! Use this rust module to do byte packing: -//! https://docs.rs/byteorder/1.2.6/byteorder/ +//! pub(crate) use _struct::make_module; diff --git a/vm/src/builtins/mod.rs b/vm/src/builtins/mod.rs index ae3b7eea2..8540e6887 100644 --- a/vm/src/builtins/mod.rs +++ b/vm/src/builtins/mod.rs @@ -1,6 +1,6 @@ //! This package contains the python basic/builtin types -//! 7 common PyRef type aliases are exposed - PyBytesRef, PyDictRef, PyIntRef, PyListRef, PyStrRef, PyTypeRef, PyTupleRef -//! Do not add more PyRef type aliases. They will be rare enough to use directly PyRef. +//! 7 common PyRef type aliases are exposed - [`PyBytesRef`], [`PyDictRef`], [`PyIntRef`], [`PyListRef`], [`PyStrRef`], [`PyTypeRef`], [`PyTupleRef`] +//! Do not add more PyRef type aliases. They will be rare enough to use directly `PyRef`. pub(crate) mod asyncgenerator; pub use asyncgenerator::PyAsyncGen; diff --git a/vm/src/dict_inner.rs b/vm/src/dict_inner.rs index c49ab752d..56ebc5eba 100644 --- a/vm/src/dict_inner.rs +++ b/vm/src/dict_inner.rs @@ -1,7 +1,7 @@ //! Ordered dictionary implementation. -//! Inspired by: https://morepypy.blogspot.com/2015/01/faster-more-memory-efficient-and-more.html -//! And: https://www.youtube.com/watch?v=p33CVV29OG8 -//! And: http://code.activestate.com/recipes/578375/ +//! Inspired by: +//! And: +//! And: use crate::{ AsObject, Py, PyExact, PyObject, PyObjectRef, PyRefExact, PyResult, VirtualMachine, diff --git a/vm/src/function/builtin.rs b/vm/src/function/builtin.rs index b8a408453..186dc7aeb 100644 --- a/vm/src/function/builtin.rs +++ b/vm/src/function/builtin.rs @@ -65,7 +65,7 @@ const fn zst_ref_out_of_thin_air(x: T) -> &'static T { } } -/// Get the [`STATIC_FUNC`](IntoPyNativeFn::STATIC_FUNC) of the passed function. The same +/// Get the STATIC_FUNC of the passed function. The same /// requirements of zero-sizedness apply, see that documentation for details. /// /// Equivalent to [`IntoPyNativeFn::into_func()`], but usable in a const context. This is only diff --git a/vm/src/import.rs b/vm/src/import.rs index 416c40a84..90aadbdbf 100644 --- a/vm/src/import.rs +++ b/vm/src/import.rs @@ -1,6 +1,5 @@ -/* - * Import mechanics - */ +//! Import mechanics + use crate::{ AsObject, PyObjectRef, PyPayload, PyRef, PyResult, TryFromObject, builtins::{PyBaseExceptionRef, PyCode, list, traceback::PyTraceback}, diff --git a/vm/src/lib.rs b/vm/src/lib.rs index 9561a9cc2..8ae5ff15d 100644 --- a/vm/src/lib.rs +++ b/vm/src/lib.rs @@ -1,9 +1,10 @@ -//! This crate contains most python logic. +//! This crate contains most of the python logic. //! -//! - Compilation -//! - Bytecode +//! - Interpreter //! - Import mechanics //! - Base objects +//! +//! Some stdlib modules are implemented here, but most of them are in the `rustpython-stdlib` module. The // to allow `mod foo {}` in foo.rs; clippy thinks this is a mistake/misunderstanding of // how `mod` works, but we want this sometimes for pymodule declarations diff --git a/vm/src/object/core.rs b/vm/src/object/core.rs index a6049884d..8edcb4dfd 100644 --- a/vm/src/object/core.rs +++ b/vm/src/object/core.rs @@ -1,14 +1,14 @@ //! Essential types for object models //! -//! +-------------------------+--------------+---------------+ -//! | Management | Typed | Untyped | -//! +-------------------------+--------------+---------------+ -//! | Interpreter-independent | Py | PyObject | -//! | Reference-counted | PyRef | PyObjectRef | -//! | Weak | PyWeakRef | PyRef | -//! +-------------------------+--------------+---------------+ +//! +-------------------------+--------------+-----------------------+ +//! | Management | Typed | Untyped | +//! +-------------------------+------------------+-------------------+ +//! | Interpreter-independent | [`Py`] | [`PyObject`] | +//! | Reference-counted | [`PyRef`] | [`PyObjectRef`] | +//! | Weak | [`PyWeakRef`] | [`PyRef`] | +//! +-------------------------+--------------+-----------------------+ //! -//! PyRef may looking like to be called as PyObjectWeak by the rule, +//! [`PyRef`] may looking like to be called as PyObjectWeak by the rule, //! but not to do to remember it is a PyRef object. use super::{ PyAtomicRef, diff --git a/vm/src/object/traverse.rs b/vm/src/object/traverse.rs index c105d23fe..46e5daff0 100644 --- a/vm/src/object/traverse.rs +++ b/vm/src/object/traverse.rs @@ -17,16 +17,16 @@ pub trait MaybeTraverse { fn try_traverse(&self, traverse_fn: &mut TraverseFn<'_>); } -/// Type that need traverse it's children should impl `Traverse`(Not `MaybeTraverse`) +/// Type that need traverse it's children should impl [`Traverse`] (not [`MaybeTraverse`]) /// # Safety -/// Please carefully read [`traverse()`] and follow the guideline +/// Please carefully read [`Traverse::traverse()`] and follow the guideline pub unsafe trait Traverse { /// impl `traverse()` with caution! Following those guideline so traverse doesn't cause memory error!: /// - Make sure that every owned object(Every PyObjectRef/PyRef) is called with traverse_fn **at most once**. /// If some field is not called, the worst results is just memory leak, /// but if some field is called repeatedly, panic and deadlock can happen. /// - /// - _**DO NOT**_ clone a `PyObjectRef` or `PyRef` in `traverse()` + /// - _**DO NOT**_ clone a [`PyObjectRef`] or [`PyRef`] in [`Traverse::traverse()`] fn traverse(&self, traverse_fn: &mut TraverseFn<'_>); } diff --git a/vm/src/prelude.rs b/vm/src/prelude.rs index 0bd0fe88b..b277f1468 100644 --- a/vm/src/prelude.rs +++ b/vm/src/prelude.rs @@ -1,3 +1,7 @@ +//! The prelude imports the various objects and traits. +//! +//! The intention is that one can include `use rustpython_vm::prelude::*`. + pub use crate::{ object::{ AsObject, Py, PyExact, PyObject, PyObjectRef, PyPayload, PyRef, PyRefExact, PyResult, diff --git a/vm/src/protocol/buffer.rs b/vm/src/protocol/buffer.rs index a3b7f125f..fcd44c11d 100644 --- a/vm/src/protocol/buffer.rs +++ b/vm/src/protocol/buffer.rs @@ -1,5 +1,5 @@ //! Buffer protocol -//! https://docs.python.org/3/c-api/buffer.html +//! use crate::{ Py, PyObject, PyObjectRef, PyPayload, PyRef, PyResult, TryFromBorrowedObject, VirtualMachine, diff --git a/vm/src/protocol/object.rs b/vm/src/protocol/object.rs index 1e972eb54..eab24f82d 100644 --- a/vm/src/protocol/object.rs +++ b/vm/src/protocol/object.rs @@ -1,5 +1,5 @@ //! Object Protocol -//! https://docs.python.org/3/c-api/object.html +//! use crate::{ AsObject, Py, PyObject, PyObjectRef, PyResult, TryFromObject, VirtualMachine, diff --git a/vm/src/readline.rs b/vm/src/readline.rs index 53647270e..54a77f128 100644 --- a/vm/src/readline.rs +++ b/vm/src/readline.rs @@ -1,3 +1,8 @@ +//! Readline interface for REPLs +//! +//! This module provides a common interface for reading lines from the console, with support for history and completion. +//! It uses the [`rustyline`] crate on non-WASM platforms and a custom implementation on WASM platforms. + use std::{io, path::Path}; type OtherError = Box; diff --git a/vm/src/suggestion.rs b/vm/src/suggestion.rs index 2bc9992d4..01f53d70c 100644 --- a/vm/src/suggestion.rs +++ b/vm/src/suggestion.rs @@ -1,3 +1,6 @@ +//! This module provides functionality to suggest similar names for attributes or variables. +//! This is used during tracebacks. + use crate::{ AsObject, Py, PyObjectRef, VirtualMachine, builtins::{PyStr, PyStrRef}, diff --git a/vm/src/version.rs b/vm/src/version.rs index 7413f8f13..9d472e8be 100644 --- a/vm/src/version.rs +++ b/vm/src/version.rs @@ -1,5 +1,4 @@ -/* Several function to retrieve version information. - */ +//! Several function to retrieve version information. use chrono::{Local, prelude::DateTime}; use std::time::{Duration, UNIX_EPOCH}; diff --git a/vm/src/vm/interpreter.rs b/vm/src/vm/interpreter.rs index cc669e066..02c71bf13 100644 --- a/vm/src/vm/interpreter.rs +++ b/vm/src/vm/interpreter.rs @@ -64,7 +64,7 @@ impl Interpreter { /// /// To finalize the vm once all desired `enter`s are called, calling `finalize` will be helpful. /// - /// See also [`run`] for managed way to run the interpreter. + /// See also [`Interpreter::run`] for managed way to run the interpreter. pub fn enter(&self, f: F) -> R where F: FnOnce(&VirtualMachine) -> R, @@ -72,13 +72,12 @@ impl Interpreter { thread::enter_vm(&self.vm, || f(&self.vm)) } - /// Run [`enter`] and call `expect_pyresult` for the result. + /// Run [`Interpreter::enter`] and call [`VirtualMachine::expect_pyresult`] for the result. /// /// This function is useful when you want to expect a result from the function, /// but also print useful panic information when exception raised. /// - /// See [`enter`] for more information. - /// See [`expect_pyresult`] for more information. + /// See also [`Interpreter::enter`] and [`VirtualMachine::expect_pyresult`] for more information. pub fn enter_and_expect(&self, f: F, msg: &str) -> R where F: FnOnce(&VirtualMachine) -> PyResult, @@ -92,11 +91,11 @@ impl Interpreter { /// Run a function with the main virtual machine and return exit code. /// /// To enter vm context only once and safely terminate the vm, this function is preferred. - /// Unlike [`enter`], `run` calls finalize and returns exit code. + /// Unlike [`Interpreter::enter`], `run` calls finalize and returns exit code. /// You will not be able to obtain Python exception in this way. /// - /// See [`finalize`] for the finalization steps. - /// See also [`enter`] for pure function call to obtain Python exception. + /// See [`Interpreter::finalize`] for the finalization steps. + /// See also [`Interpreter::enter`] for pure function call to obtain Python exception. pub fn run(self, f: F) -> u8 where F: FnOnce(&VirtualMachine) -> PyResult<()>, diff --git a/vm/src/vm/mod.rs b/vm/src/vm/mod.rs index 4b1cece8c..7baaae777 100644 --- a/vm/src/vm/mod.rs +++ b/vm/src/vm/mod.rs @@ -61,7 +61,7 @@ pub const MAX_MEMORY_SIZE: usize = isize::MAX as usize; /// Top level container of a python virtual machine. In theory you could /// create more instances of this struct and have them operate fully isolated. /// -/// To construct this, please refer to the [`Interpreter`](Interpreter) +/// To construct this, please refer to the [`Interpreter`] pub struct VirtualMachine { pub builtins: PyRef, pub sys_module: PyRef, @@ -564,7 +564,7 @@ impl VirtualMachine { /// Call Python __import__ function without from_list. /// Roughly equivalent to `import module_name` or `import top.submodule`. /// - /// See also [`import_from`] for more advanced import. + /// See also [`VirtualMachine::import_from`] for more advanced import. /// See also [`rustpython_vm::import::import_source`] and other primitive import functions. #[inline] pub fn import<'a>(&self, module_name: impl AsPyStr<'a>, level: usize) -> PyResult { diff --git a/vm/src/vm/vm_ops.rs b/vm/src/vm/vm_ops.rs index c6be959a6..df33e822a 100644 --- a/vm/src/vm/vm_ops.rs +++ b/vm/src/vm/vm_ops.rs @@ -152,9 +152,9 @@ impl VirtualMachine { /// Calling scheme used for binary operations: /// /// Order operations are tried until either a valid result or error: - /// b.rop(b,a)[*], a.op(a,b), b.rop(b,a) + /// `b.rop(b,a)[*], a.op(a,b), b.rop(b,a)` /// - /// [*] only when Py_TYPE(a) != Py_TYPE(b) && Py_TYPE(b) is a subclass of Py_TYPE(a) + /// `[*]` - only when Py_TYPE(a) != Py_TYPE(b) && Py_TYPE(b) is a subclass of Py_TYPE(a) pub fn binary_op1(&self, a: &PyObject, b: &PyObject, op_slot: PyNumberBinaryOp) -> PyResult { let class_a = a.class(); let class_b = b.class(); diff --git a/wtf8/src/lib.rs b/wtf8/src/lib.rs index 64ea42d06..3ba28a514 100644 --- a/wtf8/src/lib.rs +++ b/wtf8/src/lib.rs @@ -19,7 +19,7 @@ //! //! We use WTF-8 over something more similar to CPython's string implementation //! because of its compatibility with UTF-8, meaning that in the case where a -//! string has no surrogates, it can be viewed as a UTF-8 Rust [`str`] without +//! string has no surrogates, it can be viewed as a UTF-8 Rust [`prim@str`] without //! needing any copies or re-encoding. //! //! This implementation is mostly copied from the WTF-8 implementation in the