Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion ffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -840,7 +840,9 @@ caller imports it with no ignores.
top-level names that clash. A keyword, a member Python gives every such class, or a
method named as a field takes a trailing `_`. A member or top-level name may be a
builtin's (`bytes`, `int`): the module reads each builtin through an alias (`_bytes`).
Constructors such as `new` stay static methods: `Counter.new(1)`.
Constructors such as `new` stay static methods: `Counter.new(1)`. The module's `__all__`
lists every export, so `from moq import *` reaches one whose Rust name starts with `_`
too, and none of the module's own imports or helpers.
- **Objects** are classes owning their handle, freed once their last reference goes,
which the caller's reference keeps through a call, so there is no `close()`. A `self`
method, or passing the object by value, moves its value out, after which a call raises
Expand Down
11 changes: 11 additions & 0 deletions ffi/fixtures/api/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -5375,6 +5375,17 @@ pub fn deprecated(note: u8) -> u8 {
note
}

/// One more than `note`, by a name starting with an underscore, which `pub` still exports,
/// and which Python's module takes for its own deprecation decorator.
pub fn _deprecated(note: u8) -> u8 {
note + 1
}

/// Two more than `note`, by a name Python reserves, as the module's own `__all__` is.
pub fn __all__(note: u8) -> u8 {
note + 2
}

/// A dial, whose docs carry each rustdoc form a binding renders as its own: links to a
/// method [`Self::turn`], a field [`Dial::level`], a variant [`Error::Overflow`], a
/// function [`advance`], a constant [`LIMIT`], an object [`Counter`], a callback's method
Expand Down
133 changes: 88 additions & 45 deletions ffi/src/python.rs
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,7 @@ const TAKEN: &[&str] = &[
"_zip",
"_datetime",
"_ipaddress",
"_inspect",
"_enum",
"_socket",
"_sys",
Expand Down Expand Up @@ -112,6 +113,51 @@ const TAKEN: &[&str] = &[
"Duration",
];

/// The modules and builtins the generated Python names, each under a `_` alias [`TAKEN`] holds.
const IMPORTS: &str = "\
import abc as _abc\n\
import array as _array\n\
import asyncio as _asyncio\n\
import datetime as _datetime\n\
import ipaddress as _ipaddress\n\
import enum as _enum\n\
import inspect as _inspect\n\
import socket as _socket\n\
import sys as _sys\n\
import typing as _typing\n\
import weakref as _weakref\n\
from builtins import AttributeError as _AttributeError\n\
from builtins import BaseException as _BaseException\n\
from builtins import Exception as _Exception\n\
from builtins import ImportError as _ImportError\n\
from builtins import NotImplemented as _NotImplemented\n\
from builtins import NotImplementedError as _NotImplementedError\n\
from builtins import RuntimeError as _RuntimeError\n\
from builtins import StopAsyncIteration as _StopAsyncIteration\n\
from builtins import TypeError as _TypeError\n\
from builtins import ValueError as _ValueError\n\
from builtins import all as _all\n\
from builtins import any as _any\n\
from builtins import bool as _bool\n\
from builtins import bytearray as _bytearray\n\
from builtins import bytes as _bytes\n\
from builtins import dict as _dict\n\
from builtins import float as _float\n\
from builtins import getattr as _getattr\n\
from builtins import int as _int\n\
from builtins import isinstance as _isinstance\n\
from builtins import len as _len\n\
from builtins import list as _list\n\
from builtins import memoryview as _memoryview\n\
from builtins import object as _object\n\
from builtins import property as _property\n\
from builtins import range as _range\n\
from builtins import staticmethod as _staticmethod\n\
from builtins import str as _str\n\
from builtins import tuple as _tuple\n\
from builtins import type as _type\n\
from builtins import zip as _zip\n\n";

/// The module's `@_deprecated`, which `TAKEN` keeps an export from shadowing.
const DEPRECATOR: &str = "_T = _typing.TypeVar(\"_T\")\n\nif _typing.TYPE_CHECKING:\n\tfrom typing_extensions import deprecated as _deprecated\nelse:\n\n\tdef _deprecated(message: _str, /) -> _typing.Callable[[_T], _T]:\n\t\t\"\"\"Marks a deprecated item for type checkers.\"\"\"\n\t\treturn lambda item: item\n";

Expand Down Expand Up @@ -198,54 +244,22 @@ pub(crate) fn generate(abi: &Abi<'_>, packages: &str, contract: u64) -> Result<O
hasher.write(part.as_bytes());
}
let contract = Hasher::finish(&hasher);
// Every export, which pyright strict counts as used, so a stub of a Rust `pub fn _x` that
// only type checkers read passes, and which `from <prefix> import *` reaches, a name
// starting with `_` too. The runtime's public classes join them, as annotations name them.
let exports: BTreeSet<&str> = (g.names.keys())
.map(String::as_str)
.filter(|name| !TAKEN.contains(name))
Comment thread
pullfrog[bot] marked this conversation as resolved.
Resolved
.chain(["Duration", "ForeignReader", "Mut", "Waker"])
.collect();
let all: String = exports.iter().map(|name| format!("\t\"{name}\",\n")).collect();
let native = indent_by(NATIVE, 1);
let natives: String = g.natives.iter().map(|n| format!("\n{}", indent_by(n, 2))).collect();
let head = format!(
"# Generated by rust2-ffi: Python over the C ABI of the pub API of {packages}. Do not edit.\n\
\"\"\"The pub API of {packages}, over the CPython extension built into the library beside this file.\"\"\"\n\n\
from __future__ import annotations\n\n\
import abc as _abc\n\
import array as _array\n\
import asyncio as _asyncio\n\
import datetime as _datetime\n\
import ipaddress as _ipaddress\n\
import enum as _enum\n\
import inspect as _inspect\n\
import socket as _socket\n\
import sys as _sys\n\
import typing as _typing\n\
import weakref as _weakref\n\
from builtins import AttributeError as _AttributeError\n\
from builtins import BaseException as _BaseException\n\
from builtins import Exception as _Exception\n\
from builtins import ImportError as _ImportError\n\
from builtins import NotImplemented as _NotImplemented\n\
from builtins import NotImplementedError as _NotImplementedError\n\
from builtins import RuntimeError as _RuntimeError\n\
from builtins import StopAsyncIteration as _StopAsyncIteration\n\
from builtins import TypeError as _TypeError\n\
from builtins import ValueError as _ValueError\n\
from builtins import all as _all\n\
from builtins import any as _any\n\
from builtins import bool as _bool\n\
from builtins import bytearray as _bytearray\n\
from builtins import bytes as _bytes\n\
from builtins import dict as _dict\n\
from builtins import float as _float\n\
from builtins import getattr as _getattr\n\
from builtins import int as _int\n\
from builtins import isinstance as _isinstance\n\
from builtins import len as _len\n\
from builtins import list as _list\n\
from builtins import memoryview as _memoryview\n\
from builtins import object as _object\n\
from builtins import property as _property\n\
from builtins import range as _range\n\
from builtins import staticmethod as _staticmethod\n\
from builtins import str as _str\n\
from builtins import tuple as _tuple\n\
from builtins import type as _type\n\
from builtins import zip as _zip\n\n\
{IMPORTS}__all__ = [\n{all}]\n\n\
if _typing.TYPE_CHECKING:\n\
\timport dataclasses as _dataclasses\n\n\
_T = _typing.TypeVar(\"_T\")\n\n\n\
Expand Down Expand Up @@ -507,9 +521,13 @@ impl<'a> Gen<'a> {
self.classes.get(c).cloned().unwrap_or_else(|| pascal(self.bare(c)))
}

/// The module-level Python name `what` takes, `name` unless that is taken.
/// The module-level Python name `what` takes, `name` unless that is taken. Python
/// defines `__x__` names, such as the module's own `__all__` and `__getattr__`, which
/// one takes a trailing `_` past.
fn claim(&mut self, name: &str, what: String) -> String {
abi::claim(&mut self.names, |_| false, name, what)
let dunder =
|name: &str| name.len() > 4 && name.starts_with("__") && name.ends_with("__") && !name.ends_with("___");
abi::claim(&mut self.names, dunder, name, what)
}

/// Register the class the Python expression `py` names under `key`, returning the
Expand Down Expand Up @@ -817,6 +835,8 @@ impl<'a> Gen<'a> {
if abi.ranges.values().any(|ty| matches!(ty, Type::Bound(_))) {
let bound = abi.rt("bound");
self.register(&bound, "Bound".to_string());
self.names
.insert("Bound".to_string(), "the runtime's range bound".to_string());
self.py.push_str(
"class Bound(_enum.Enum):\n\t\"\"\"What a range's start or end bound does: nothing, include its value, or exclude it.\"\"\"\n\n\tUNBOUNDED = 0\n\tINCLUDED = 1\n\tEXCLUDED = 2\n\n\n",
);
Expand All @@ -827,6 +847,7 @@ impl<'a> Gen<'a> {
for (c, n) in &abi.arrays {
let name = Abi::array_class(*n);
self.register(c, name.clone());
self.names.insert(name.clone(), format!("the class of `[u8; {n}]`"));
let _ = write!(
self.py,
"class {name}(_bytes):\n\t\"\"\"A Rust `[u8; {n}]`: exactly {n} bytes.\"\"\"\n\n\t__slots__ = ()\n\n\tdef __new__(cls, value: {BUFFER}) -> _typing.Self:\n\t\tself = _bytes.__new__(cls, value)\n\t\tif _len(self) != {n}:\n\t\t\traise _ValueError(f\"{{_len(self)}} bytes, not {n}\")\n\t\treturn self\n\n\n"
Expand Down Expand Up @@ -1068,6 +1089,7 @@ impl<'a> Gen<'a> {
other => unreachable!("{other:?} is no range"),
};
self.register(c, name.clone());
self.names.insert(name.clone(), "a range's class".to_string());
let fields: Vec<Slot> = (fields.into_iter())
.map(|(name, ty)| Slot {
name: name.to_string(),
Expand Down Expand Up @@ -2706,9 +2728,30 @@ fn record_class(name: &str, bases: &str, docs: &str, fields: &[Slot], members: &

#[cfg(test)]
mod tests {
use super::{DEPRECATOR, TAKEN, member, param_name, param_names, variant_classes};
use super::{DEPRECATOR, IMPORTS, RUNTIME, TAKEN, member, param_name, param_names, variant_classes};
use crate::ir::{Param, Type};

/// Every alias the module imports, and every `_` name the runtime binds at module level,
/// is taken, so no export rebinds one the generated code reads.
#[test]
fn module_names_taken() {
let aliases = IMPORTS
.lines()
.filter_map(|line| line.split_once(" as ").map(|(_, name)| name));
let bound = RUNTIME.lines().filter_map(|line| {
let line = (line.strip_prefix("async def ").or_else(|| line.strip_prefix("def ")))
.or_else(|| line.strip_prefix("class "))
.unwrap_or(line);
let end = line
.find(|c: char| !(c == '_' || c.is_alphanumeric()))
.unwrap_or(line.len());
Some(&line[..end]).filter(|name| name.starts_with('_') && name.len() > 1)
});
for name in aliases.chain(bound) {
assert!(TAKEN.contains(&name), "the module's `{name}` is not in TAKEN");
}
}

/// Every name the deprecation helper binds is taken, so no export shadows it.
#[test]
fn deprecator_names_taken() {
Expand Down
4 changes: 3 additions & 1 deletion ffi/surface/api/c.h
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
#ifdef __cplusplus
extern "C" {
#endif
#define API_CONTRACT ((uint64_t)0x2dadf0e4743d1bb3ULL)
#define API_CONTRACT ((uint64_t)0x3838b15609e6d19bULL)
uint64_t api_contract(void);
uint32_t api_target(void);
typedef int32_t api_status;
Expand Down Expand Up @@ -2495,6 +2495,8 @@ API_MUST_USE api_poll api_unescaped_maybe_poll(api_unescaped_maybe_future *futur
void api_unescaped_maybe_future_free(api_unescaped_maybe_future *future);
API_MUST_USE api_buf api_unzeroed(api_buf bytes);
uint8_t api_deprecated(uint8_t note);
uint8_t api__deprecated(uint8_t note);
uint8_t api___all__(uint8_t note);
api_Knob api_knob(api_Dial dial);
typedef struct api_level_later_future api_level_later_future;
API_MUST_USE api_level_later_future *api_level_later(api_Dial dial);
Expand Down
2 changes: 2 additions & 0 deletions ffi/surface/api/cpp.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -1792,6 +1792,8 @@ namespace api {
inline ::api::unescaped_maybe_future unescaped_maybe(::std::optional<::api::input> text);
inline ::api::buf unzeroed(::api::input bytes);
inline ::std::uint8_t deprecated(::std::uint8_t note);
inline ::std::uint8_t _deprecated(::std::uint8_t note);
inline ::std::uint8_t __all___(::std::uint8_t note);
[[deprecated]] inline ::api::Knob knob(const ::api::Dial &dial);
[[deprecated("read its `level`")]] inline ::api::level_later_future level_later(const ::api::Dial &dial);
inline ::api::result<::api::Dial, ::api::Error> turned(const ::api::Dial &dial, ::std::unique_ptr<::api::Turner> turner);
Expand Down
2 changes: 2 additions & 0 deletions ffi/surface/api/dart.dart
Original file line number Diff line number Diff line change
Expand Up @@ -1940,6 +1940,8 @@ Cancelable<String> unescapedLater(String text);
Cancelable<String?> unescapedMaybe(String? text);
typed.Uint8List unzeroed(typed.Uint8List bytes);
int deprecated(int note);
int deprecated_(int note);
int all(int note);
@Deprecated('') Knob knob(Dial dial);
@Deprecated('read its `level`') Cancelable<U64> levelLater(Dial dial);
Dial turned(Dial dial, Turner turner);
Expand Down
2 changes: 2 additions & 0 deletions ffi/surface/api/go.txt
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ const URL uint64 = 1000
FUNCTIONS
func Admit(entry p_rt.Tuple4[*Counter, *Mark, Seat, Choice]) (uint64, error)
func After(ctx context.Context, first func(context.Context), value uint32) (uint32, error)
func All(note uint8) uint8
func Alpn(config *p_tls.Config) (string, error)
func AlpnLent(config *p_tls.Config) (string, error)
func ApplyNonZeroU16(pair PairNonZeroU16, f func(uint16) uint32) (uint32, error)
Expand Down Expand Up @@ -52,6 +53,7 @@ func Crammed(a Moment, b Moment, n0 uint64, n1 uint64, n2 uint64, n3 uint64, n4
func Cross(left LeftRightU8, right RightLeftU8) uint8
func Crowded(reading Reading, a Stamp, b Stamp, n0 uint64, n1 uint64, n2 uint64, n3 uint64, n4 uint64, n5 uint64, n6 uint64, n7 uint64, n8 uint64, n9 uint64, n10 uint64, n11 uint64, n12 uint64, n13 uint64, n14 uint64, n15 uint64, n16 uint64, n17 uint64, n18 uint64, n19 uint64, n20 uint64, n21 uint64, n22 uint64, n23 uint64, n24 uint64, n25 uint64, n26 uint64, n27 uint64, n28 uint64, n29 uint64, n30 uint64, n31 uint64, n32 uint64, n33 uint64, n34 uint64, n35 uint64, n36 uint64, n37 uint64, n38 uint64, n39 uint64, n40 uint64, n41 uint64, n42 uint64, n43 uint64, n44 uint64, n45 uint64, n46 uint64, n47 uint64, n48 uint64, n49 uint64, n50 uint64, n51 uint64, n52 uint64, n53 uint64, n54 uint64, n55 uint64, n56 uint64, n57 uint64, n58 uint64, n59 uint64, n60 uint64, n61 uint64, n62 uint64, n63 uint64, n64 uint64, n65 uint64, n66 uint64, n67 uint64, n68 uint64, n69 uint64, n70 uint64, n71 uint64, n72 uint64, n73 uint64, n74 uint64, n75 uint64, n76 uint64, n77 uint64, n78 uint64, n79 uint64, n80 uint64, n81 uint64, n82 uint64, n83 uint64, n84 uint64, n85 uint64, n86 uint64, n87 uint64, n88 uint64, n89 uint64, n90 uint64, n91 uint64, n92 uint64, n93 uint64, n94 uint64, n95 uint64, n96 uint64, n97 uint64, n98 uint64, n99 uint64, n100 uint64, n101 uint64, n102 uint64, n103 uint64, n104 uint64, n105 uint64, n106 uint64, n107 uint64, n108 uint64, n109 uint64, n110 uint64, n111 uint64, n112 uint64, n113 uint64, n114 uint64, n115 uint64, n116 uint64, n117 uint64, n118 uint64) (uint64, error)
func Deprecated_(note uint8) uint8
func Deprecated__(note uint8) uint8
func Describe(event Event) (string, error)
func DescribeNonZeros(nonZeros NonZeros) (string, error)
func Digit(r *p_rt.Bytes) (uint8, error)
Expand Down
2 changes: 2 additions & 0 deletions ffi/surface/api/kotlin.kt
Original file line number Diff line number Diff line change
Expand Up @@ -1683,6 +1683,8 @@ suspend fun unescapedLater(text: kotlin.String): kotlin.String
suspend fun unescapedMaybe(text: kotlin.String?): kotlin.String?
fun unzeroed(bytes: api.Bytes): api.Bytes
fun deprecated(note: kotlin.UByte): kotlin.UByte
fun deprecated_(note: kotlin.UByte): kotlin.UByte
fun all(note: kotlin.UByte): kotlin.UByte
@kotlin.Deprecated("") fun knob(dial: api.Dial): api.Knob
@kotlin.Deprecated("read its `level`") suspend fun levelLater(dial: api.Dial): kotlin.ULong
@kotlin.jvm.Throws(ErrorException::class) fun turned(dial: api.Dial, turner: api.Turner): api.Dial
Expand Down
Loading