Coding standards
Standard Rust naming, ownership, and error handling. Python follows the same public vocabulary through its native bindings.
Naming
| Surface | Convention |
|---|---|
| Modules and files | snake_case: matrix, ml::loss, video_decoder.rs |
| Types and variants | PascalCase: Matrix, VideoDecoder, ErrorKind |
| Functions and methods | snake_case: mat_mul_nt, read_f32, decode_file |
| Fields, parameters, locals | snake_case: device_id, input_matrix, output |
| Constants and statics | SCREAMING_SNAKE_CASE; OA-owned constants use the OA_ prefix under the repository rule |
| Acronyms | Rust casing: Gpu, Cpu, Api, Id |
Use Rust primitives directly: u32, usize, f32, and bool. Use Vec<T>, String,Option<T>, and standard ownership types when their contracts fit. Semantic newtypes belong where they prevent a real category error.
Modules own operations
Stateless operations are free functions in lowercase modules:oa::matrix::mat_mul_nt, oa::ml::loss::mse, andoa::image::resize. Core numerical operations belong to oa::matrix; ML extensions belong to oa::ml::matrix. Each operation has one owning implementation.
Values and real stateful sessions remain named types. Root re-exports such asoa::Matrix and oa::AudioPlayer retain the same type identity as their owning modules. The type reference distinguishes structs, enums, traits, and aliases. Python exposes classes for bound values and sessions; its available surface is indexed separately.
Ownership and failure
Prefer private fields and checked constructors. Shared access uses &T; mutation uses &mut T. Use Copy only for small independent values and Clone when its retained-handle semantics are explicit. Fallible native operations return oa::Result<T> and propagate oa::Error with ?. Python translates native failures to exceptions.
Constructors receive an Engine when ownership cannot be inferred from an input value. Operations on device-backed values infer their owner and reject mixed engines. Host reads are explicit completion boundaries. Stateful terminal operations such asclose, flush, or drain report failure explicitly;Drop does not perform them implicitly.
Rust and Python at the call site
1use oa::{Engine, Matrix, matrix};23fn multiply(left: &Matrix, right: &Matrix) -> oa::Result<Matrix> {4 matrix::mat_mul_nt(left, right)5}67fn main() -> oa::Result<()> {8 let engine = Engine::new()?;9 let left = matrix::ones(&engine, [2, 3])?;10 let right = matrix::full(&engine, [2, 3], 2.0)?;11 let output = multiply(&left, &right)?;12 assert_eq!(output.read_f32()?, vec![6.0; 4]);13 Ok(())14}15
Python uses lowercase modules, PascalCase classes, and snake_case functions, methods, parameters, and locals. Caller aliases such as import oa.core as oac are ordinary local abbreviations. Rust callers can use use oa::matrix as matrices.
Formatting and documentation
Run cargo fmt with OA's checked rustfmt.toml:hard_tabs = true and tab_spaces = 2. Function signatures wrap according to the formatter. Document ownership, accepted inputs, errors, host boundaries, and lifecycle transitions in rustdoc. Schema-owned declarations are changed through their generator.
Public source: formatter settings, Rust API, and Python facades.