youknowone · Nov 10, 2026 · Nov 9, 2026 · Nov 9, 2026 · Nov 10, 2026
diff --git a/crates/derive-impl/src/pymodule.rs b/crates/derive-impl/src/pymodule.rs
@@ -4,8 +4,8 @@ use crate::metadata::{AttributeDoc, NestedMeta};
 use crate::pystructseq::PyStructSequenceMeta;
 use crate::util::{
     ALL_ALLOWED_NAMES, AttrItemMeta, AttributeExt, ClassItemMeta, ContentItem, ContentItemInner,
-    ErrorVec, ItemMeta, ItemNursery, ModuleItemMeta, SimpleItemMeta, internal_doc_tokens,
-    iter_use_idents, pyclass_ident_and_attrs,
+    ErrorVec, FunctionItemMeta, ItemMeta, ItemNursery, ModuleItemMeta, SimpleItemMeta,
+    flags_signature_doc_tokens, internal_doc_tokens, iter_use_idents, pyclass_ident_and_attrs,
 };
 use core::str::FromStr;
 use proc_macro2::{Delimiter, Group, TokenStream, TokenTree};
@@ -674,14 +674,15 @@ impl ModuleItem for FunctionItem {
         let ident = &func.sig().ident;
 
         let item_attr = args.attrs.remove(self.index());
-        let item_meta = SimpleItemMeta::from_attr(ident.clone(), &item_attr)?;
+        let item_meta = FunctionItemMeta::from_attr(ident.clone(), &item_attr)?;
 
         let py_name = item_meta.simple_name()?;
+        let mut flags_signatures = vec![item_meta.signature_from_flags()?];
         let mut py_names = vec![py_name];
         for attr_index in self.py_attrs.iter().rev() {
             let mut loop_unit = || {
                 let attr_attr = args.attrs.remove(*attr_index);
-                let item_meta = SimpleItemMeta::from_attr(ident.clone(), &attr_attr)?;
+                let item_meta = FunctionItemMeta::from_attr(ident.clone(), &attr_attr)?;
 
                 let py_name = item_meta.simple_name()?;
                 if py_names.iter().any(|name| name == &py_name) {
@@ -690,6 +691,7 @@ impl ModuleItem for FunctionItem {
                         &format!("`{py_name}` is duplicated name for multiple py* attribute"),
                     ));
                 }
+                flags_signatures.push(item_meta.signature_from_flags()?);
                 py_names.push(py_name);
                 Ok(())
             };
@@ -701,7 +703,8 @@ impl ModuleItem for FunctionItem {
         let rust_doc = args.attrs.doc().filter(|doc| !doc.is_empty());
         let docs = py_names
             .iter()
-            .map(|py_name| {
+            .zip(flags_signatures)
+            .map(|(py_name, from_flags)| {
                 let db_doc = if rust_doc.is_some() {
                     None
                 } else {
@@ -710,7 +713,11 @@ impl ModuleItem for FunctionItem {
                     })
                 };
                 let doc = crate::class_docs::item_doc_tokens(db_doc, rust_doc.clone());
-                internal_doc_tokens(func.sig(), py_name, None, doc, None, Some("$module"))
+                if from_flags {
+                    flags_signature_doc_tokens(func.sig(), py_name, doc)
+                } else {
+                    internal_doc_tokens(func.sig(), py_name, None, doc, None, Some("$module"))
+                }
             })
             .collect();
 

diff --git a/crates/derive-impl/src/util.rs b/crates/derive-impl/src/util.rs
@@ -319,6 +319,26 @@ impl ItemMeta for SimpleItemMeta {
     }
 }
 
+/// Module function metadata; flag-derived signatures deliberately opt out of Clinic text.
+pub(crate) struct FunctionItemMeta(pub ItemMetaInner);
+
+impl ItemMeta for FunctionItemMeta {
+    const ALLOWED_NAMES: &'static [&'static str] = &["name", "signature_from_flags"];
+
+    fn from_inner(inner: ItemMetaInner) -> Self {
+        Self(inner)
+    }
+    fn inner(&self) -> &ItemMetaInner {
+        &self.0
+    }
+}
+
+impl FunctionItemMeta {
+    pub(crate) fn signature_from_flags(&self) -> Result<bool> {
+        self.inner()._bool("signature_from_flags")
+    }
+}
+
 pub(crate) struct ModuleItemMeta(pub ItemMetaInner);
 
 impl ItemMeta for ModuleItemMeta {
@@ -902,6 +922,30 @@ pub(crate) fn internal_doc_tokens(
     leading_marker: Option<&str>,
 ) -> TokenStream {
     let args_const = args_const(&sig_pieces(sig, implicit_self, self_ty, leading_marker));
+    doc_from_signature_args(py_name, doc, args_const)
+}
+
+/// CPython's flags-based fallback, evaluated entirely during compilation.
+pub(crate) fn flags_signature_doc_tokens(
+    sig: &Signature,
+    py_name: &str,
+    doc: TokenStream,
+) -> TokenStream {
+    let original = args_const(&sig_pieces(sig, None, None, None));
+    let args = quote! {
+        const ARGS: &[::rustpython_vm::function::SigArg] = {
+            #original
+            ::rustpython_vm::function::signature_from_flags(ARGS)
+        };
+    };
+    doc_from_signature_args(py_name, doc, args)
+}
+
+fn doc_from_signature_args(
+    py_name: &str,
+    doc: TokenStream,
+    args_const: TokenStream,
+) -> TokenStream {
     quote! {
         {
             #args_const
@@ -967,6 +1011,38 @@ mod metadata_tests {
         )
     }
 
+    #[test]
+    fn signature_from_flags_is_a_module_function_only_opt_in() {
+        let attr = parse_quote!(#[pyfunction(name = "alias", signature_from_flags)]);
+        let meta = FunctionItemMeta::from_attr(parse_quote!(function), &attr).unwrap();
+        assert_eq!(meta.simple_name().unwrap(), "alias");
+        assert!(meta.signature_from_flags().unwrap());
+        let ordinary = parse_quote!(#[pyfunction]);
+        assert!(
+            !FunctionItemMeta::from_attr(parse_quote!(function), &ordinary)
+                .unwrap()
+                .signature_from_flags()
+                .unwrap()
+        );
+        assert!(SimpleItemMeta::from_attr(parse_quote!(function), &attr).is_err());
+        let invalid = parse_quote!(#[pyfunction(signature_from_flags = "arbitrary text")]);
+        let result = FunctionItemMeta::from_attr(parse_quote!(function), &invalid);
+        assert!(result.and_then(|meta| meta.signature_from_flags()).is_err());
+    }
+
+    #[test]
+    fn signature_from_flags_codegen_preserves_original_argument_metadata() {
+        let sig: Signature = parse_quote!(fn sample(value: ValueArgs, vm: &VirtualMachine));
+        let doc = quote!(::rustpython_vm::function::ItemDoc::NONE);
+        let from_flags = flags_signature_doc_tokens(&sig, "sample", doc.clone()).to_string();
+        assert!(from_flags.contains("signature_from_flags"));
+        assert!(from_flags.contains("ValueArgs"));
+        let ordinary =
+            internal_doc_tokens(&sig, "sample", None, doc, None, Some("$module")).to_string();
+        assert!(!ordinary.contains("signature_from_flags"));
+        assert!(ordinary.contains("$module"));
+    }
+
     #[test]
     fn option_validation_keeps_contextual_diagnostics() {
         assert_eq!(

diff --git a/crates/derive/src/lib.rs b/crates/derive/src/lib.rs
@@ -363,6 +363,14 @@ pub fn pyexception(attr: TokenStream, item: TokenStream) -> TokenStream {
 /// }
 /// ```
 /// ### pyfunction
+///
+/// `#[pyfunction(signature_from_flags)]` displays CPython's non-Clinic
+/// `METH_NOARGS` / `METH_O` signature (`$self`, and `object` for one argument).
+/// Compilation rejects anything other than zero or one required positional-only
+/// argument. It changes only the generated text, not module ownership or calls.
+/// Use this only where CPython derives the signature from its method flags;
+/// ordinary functions retain their generated Clinic-style signature.
+///
 /// This is used to create a python function.
 /// #### Function signature
 /// The last argument can optionally be of the type `&VirtualMachine` to access the VM.

diff --git a/crates/stdlib/src/cjkcodecs.rs b/crates/stdlib/src/cjkcodecs.rs
@@ -17,7 +17,7 @@ macro_rules! codecs_module {
 
             const CODECS: &[&'static str] = &[$($name),+];
 
-            #[pyfunction]
+            #[pyfunction(signature_from_flags)]
             fn getcodec(object: PyObjectRef, vm: &VirtualMachine) -> PyResult {
                 multibytecodec::get_codec(CODECS, &object, vm)
             }

diff --git a/crates/stdlib/src/socket.rs b/crates/stdlib/src/socket.rs
@@ -3365,7 +3365,7 @@ mod _socket {
         (String::new(), 0).to_pyobject(vm)
     }
 
-    #[pyfunction]
+    #[pyfunction(signature_from_flags)]
     fn gethostname(vm: &VirtualMachine) -> PyResult<PyStrRef> {
         vm.audit("socket.gethostname", || ())?;
 
@@ -3916,7 +3916,7 @@ mod _socket {
         target_os = "netbsd",
         target_os = "openbsd",
     ))]
-    #[pyfunction]
+    #[pyfunction(signature_from_flags)]
     fn if_nameindex(vm: &VirtualMachine) -> PyResult<Vec<PyObjectRef>> {
         #[cfg(not(windows))]
         {
@@ -4120,13 +4120,13 @@ mod _socket {
 
     static DEFAULT_TIMEOUT: AtomicCell<f64> = AtomicCell::new(-1.0);
 
-    #[pyfunction]
+    #[pyfunction(signature_from_flags)]
     fn getdefaulttimeout() -> Option<f64> {
         let timeout = DEFAULT_TIMEOUT.load();
         if timeout >= 0.0 { Some(timeout) } else { None }
     }
 
-    #[pyfunction]
+    #[pyfunction(signature_from_flags)]
     fn setdefaulttimeout(object: Option<ArgIntoFloat>, vm: &VirtualMachine) -> PyResult<()> {
         let val = match object {
             Some(t) => {
@@ -4145,7 +4145,7 @@ mod _socket {
         Ok(())
     }
 
-    #[pyfunction]
+    #[pyfunction(signature_from_flags)]
     fn dup(object: PyObjectRef, vm: &VirtualMachine) -> Result<RawSocket, IoOrPyException> {
         let sock = get_raw_sock(&object, vm)?;
         let sock = core::mem::ManuallyDrop::new(sock_from_raw(sock, vm)?);
@@ -4156,7 +4156,7 @@ mod _socket {
         Ok(fd)
     }
 
-    #[pyfunction]
+    #[pyfunction(signature_from_flags)]
     fn close(object: PyObjectRef, vm: &VirtualMachine) -> Result<(), IoOrPyException> {
         Ok(close_inner(get_raw_sock(&object, vm)?)?)
     }

diff --git a/crates/stdlib/src/socket_wasm.rs b/crates/stdlib/src/socket_wasm.rs
@@ -143,15 +143,15 @@ mod _socket {
         }
     }
 
-    #[pyfunction]
+    #[pyfunction(signature_from_flags)]
     fn getdefaulttimeout() -> Option<f64> {
         let timeout = f64::from_bits(DEFAULT_TIMEOUT.load(Ordering::Relaxed));
         (timeout >= 0.0).then_some(timeout)
     }
 
-    #[pyfunction]
-    fn setdefaulttimeout(timeout: Option<ArgIntoFloat>, vm: &VirtualMachine) -> PyResult<()> {
-        match timeout {
+    #[pyfunction(signature_from_flags)]
+    fn setdefaulttimeout(object: Option<ArgIntoFloat>, vm: &VirtualMachine) -> PyResult<()> {
+        match object {
             None => DEFAULT_TIMEOUT.store((-1.0f64).to_bits(), Ordering::Relaxed),
             Some(value) => {
                 let value = value.into_float();
@@ -167,7 +167,7 @@ mod _socket {
         Ok(())
     }
 
-    #[pyfunction]
+    #[pyfunction(signature_from_flags)]
     fn gethostname(vm: &VirtualMachine) -> PyResult<String> {
         Err(unsupported(vm, "gethostname").into())
     }

diff --git a/crates/stdlib/src/uuid.rs b/crates/stdlib/src/uuid.rs
@@ -29,7 +29,7 @@ mod _uuid {
     }
 
     #[cfg(not(windows))]
-    #[pyfunction]
+    #[pyfunction(signature_from_flags)]
     fn generate_time_safe() -> (Vec<u8>, PyNone) {
         static CONTEXT: ContextV1 = ContextV1::new(0);
         let ts = Timestamp::now(&CONTEXT);

diff --git a/crates/vm/src/function/mod.rs b/crates/vm/src/function/mod.rs
@@ -44,7 +44,8 @@ pub use number::{
 pub use protocol::{ArgCallable, ArgIterable, ArgMapping, ArgSequence};
 pub use signature::{
     DefaultRepr, Param, ParamKind, SigArg, choose_class_params, has_signature, internal_doc_bytes,
-    internal_doc_len, real_signature, signature_prefix_bytes, signature_prefix_len,
+    internal_doc_len, real_signature, signature_from_flags, signature_prefix_bytes,
+    signature_prefix_len,
 };
 pub use time::TimeoutSeconds;