Skip to content

Volume 17: Standard Library

1. Introduction

This volume defines the scope, philosophy, organization, and initial contents of the Rethon standard library. It describes the standard library philosophy, standard library scope, core types, primitive type support, collections, iteration utilities, result and option types, error types and error protocols, string and text utilities, numeric utilities, time and date, file and path APIs, basic I/O, async utilities, testing support, package boundary, excluded domains, stability and compatibility, future extensions, and summary.

This document is part of the official Rethon Language Specification. It is normative rather than descriptive. Implementations, tooling, documentation systems, and other source-processing tools shall treat the rules in this volume as authoritative.

This volume does not define package manager behavior, distribution machinery, platform-specific deployment mechanics, or backend implementation details. It defines the source-level and language-level boundary of the standard library.

Rethon is Python-inspired in language philosophy and Python-first in surface syntax where practical. It is statically typed, AOT compiled, memory-safe by default, protocol-oriented, value-oriented, and ownership-transparent.

The standard library shall be general-purpose.

2. Standard Library Philosophy

The standard library shall provide broadly useful, conservative, and stable APIs that support ordinary application development.

The standard library shall favor readability, static typing, explicit contracts, and long-term compatibility.

The standard library shall prefer small, composable APIs over large specialized frameworks.

The standard library shall not attempt to include every domain-specific capability in the language ecosystem.

Example:

from text import split_lines
from path import Path

The standard library shall serve as the core source-level foundation for common programming tasks.

The standard library shall remain compatible with the language's Python-first surface direction and its protocol-oriented, value-oriented type model.

3. Standard Library Scope

The standard library shall include the common general-purpose APIs needed for ordinary application code.

The standard library shall include at minimum:

  • core types
  • primitive type support
  • collections
  • iteration utilities
  • result and option types
  • error types and error protocols
  • string and text utilities
  • numeric utilities
  • time and date utilities
  • file and path APIs
  • basic I/O
  • async utilities
  • testing support

The standard library shall not be a game engine, graphics stack, audio stack, or physics framework.

The standard library shall not include engine-specific APIs.

The standard library shall not include Gamepenter integration.

Domain-specific functionality shall be delivered through installable RETPAK packages rather than through the core standard library.

4. Core Types

The standard library shall provide the core reusable types needed by ordinary language features and common APIs.

The core standard-library types shall include:

  • Result<T, E>
  • Option<T>
  • Error
  • Iterable<T>
  • Iterator<T>
  • common text and path types needed by the standard library APIs

Example:

def parse_name(text: str) -> Result<str, Error>:
    ...

Core types shall be statically typed.

Core types shall be documented and stabilized conservatively because many higher-level APIs depend on them.

5. Primitive Type Support

The standard library shall provide utilities that support the language's primitive types.

The standard library shall support int, float, bool, char, and str through formatting, conversion, comparison helpers, parsing, and related general-purpose functionality.

Example:

let value: int = parse_int("42")
let text: str = format_int(value)

Primitive type support shall remain conservative and broadly applicable.

The standard library shall not replace the primitive type model defined by the language specification.

6. Collections

The standard library shall include the initial collection family defined by the collections and iteration volume.

The standard library shall provide collection APIs for:

  • list<T>
  • dict<K, V>
  • set<T>
  • tuple<T1, T2, ...>
  • range

Example:

values: list<int> = [1, 2, 3]

Collection APIs shall be generic, statically typed, and value-oriented where appropriate.

Collection utilities shall be conservative and shall not depend on hidden domain-specific behavior.

7. Iteration Utilities

The standard library shall provide iteration utilities for working with iterables and iterators.

The standard library shall support the core iterable and iterator protocols and common helpers for transforming, filtering, consuming, or adapting iterables where such helpers remain readable and general-purpose.

Example:

for item in items:
    print(item)

Iteration utilities shall preserve the language's explicit, protocol-based iteration model.

The standard library shall not replace the language's for-in syntax with library-only iteration idioms.

8. Result and Option Types

The standard library shall include Result<T, E> and Option<T>.

These types shall be core Standard Library abstractions for explicit recoverable-failure modeling and explicit optional-presence modeling.

Example:

def lookup_user(id: int) -> Result<User, Error>:
    ...

Result<T, E> and Option<T> shall be stable, core abstractions because many APIs depend on them for explicit typed control flow.

The language-level definition of nullable types and the None absence literal is defined in the type-system volume. The normative behavior of Result<T, E> and Option<T> is defined in the error-handling volume.

Pattern matching and the error-handling volume shall remain compatible with these types.

9. Error Types and Error Protocols

The standard library shall include the core Error protocol or base error contract used by ordinary language and library APIs.

The standard library shall include common error utilities needed for readable diagnostics, formatting, propagation, and matching.

Example:

protocol Error:
    message: str

Error support in the standard library shall remain compatible with the language's typed error-handling model.

The standard library shall not commit to a runtime exception implementation detail in its source-level API design.

10. String and Text Utilities

The standard library shall include general-purpose string and text utilities.

Such utilities may include splitting, joining, trimming, searching, formatting, parsing, encoding-adjacent helpers, and other broadly useful text operations.

Example:

parts = split(text, ",")

Text utilities shall remain conservative, predictable, and readable.

The standard library shall not turn text processing into a domain-specific framework.

11. Numeric Utilities

The standard library shall include general-purpose numeric utilities.

Such utilities may include comparison helpers, parsing, formatting, clamping, bounds checks, and common math-adjacent operations appropriate for ordinary application code.

Example:

let bounded = clamp(value, min: 0, max: 100)

Numeric utilities shall remain consistent with the language's primitive numeric types and static typing rules.

The standard library shall not require specialized numeric abstraction machinery for ordinary code.

12. Time and Date

The standard library shall include time and date utilities suitable for ordinary application logic.

Such utilities may include timestamps, durations, clocks, calendars, and formatting helpers where they are generally useful.

Example:

let elapsed = Duration(seconds: 5)

Time and date APIs shall remain conservative and broadly useful.

The standard library shall not force application code to depend on platform-specific time behavior in its source-level design.

13. File and Path APIs

The standard library shall include file and path APIs.

Such APIs shall support common filesystem operations, path manipulation, file metadata access, and related general-purpose tasks.

Example:

let path = Path.from_string("/tmp/input.txt")

File and path APIs shall be explicit and statically typed.

File and path APIs shall remain compatible with the language's memory model and error-handling model.

The standard library shall not define platform-specific filesystem behavior beyond what is necessary for portable source-level use.

14. Basic I/O

The standard library shall include basic I/O facilities.

Such facilities shall cover ordinary input and output tasks such as reading, writing, buffering, and console interaction where appropriate.

Example:

print("Hello")

Basic I/O shall remain general-purpose and conservative.

The standard library shall not elevate interactive shell behavior or platform-specific console extensions into core language requirements.

15. Async Utilities

The standard library shall include basic async utilities that support the language's initial async model.

Such utilities may include task helpers, simple scheduling interfaces, awaitable adapters, or other minimal general-purpose helpers consistent with the language's async direction.

Example:

async def main() -> None:
    user = await load_user(1)

Async utilities shall remain small and shall not replace the core async syntax defined by the language.

The standard library shall not commit to a specific scheduler implementation in its public source-level contract.

16. Testing Support

The standard library shall include testing support suitable for ordinary language and library development.

Testing support may include assertions, test discovery helpers, matchers, fixtures, or minimal test-runner integration appropriate for the core distribution.

Example:

def test_parse_name() -> None:
    assert parse_name("Ada") == "Ada"

Testing support shall be general-purpose and shall not require domain-specific frameworks.

The standard library shall provide enough testing support to make ordinary package and application testing practical without forcing users into unrelated external dependencies.

17. Package Boundary

The standard library shall define the core general-purpose APIs that ship with the language distribution.

Installable RETPAK packages shall provide external and domain-specific capabilities that are intentionally outside the standard library.

The package boundary shall keep the standard library conservative, stable, and broadly useful.

The standard library shall not absorb external domain APIs merely because they are popular in one application category.

18. Excluded Domains

The standard library shall exclude the following domains from the core distribution:

  • game-specific APIs
  • engine-specific APIs
  • graphics APIs
  • audio APIs
  • physics APIs
  • Gamepenter integration
  • other specialized domain frameworks that are not general-purpose

Example of excluded direction:

# game engine integration is not part of the core standard library

These domains shall be provided through installable RETPAK packages if and when the ecosystem needs them.

Networking may be provided only in a minimal, conservative form or deferred to a later volume or package if the language decides that such APIs are not yet ready for the core distribution.

19. Stability and Compatibility

The standard library shall be stable, typed, readable, and conservative.

Public standard-library APIs shall change only when there is a clear compatibility and maintenance justification.

The standard library shall favor additive evolution over disruptive redesign.

The standard library shall preserve source compatibility where practical.

When a standard-library API must evolve incompatibly, the change shall be made with explicit versioning or transition planning suitable for a long-lived language ecosystem.

20. Future Extensions

This volume defines the current direction for the Rethon standard library, but future specification work may refine the library in carefully controlled ways.

Possible future extensions include:

  • richer text formatting and parsing APIs
  • more extensive numeric helpers
  • additional time and date abstractions
  • networking APIs if justified later
  • richer async utilities
  • more ergonomic testing helpers
  • additional portable OS-adjacent utilities

Any future extension shall preserve the current direction:

  • the standard library remains general-purpose
  • core types, collections, result/option, error, iterable, and iterator support remain central
  • file, path, and basic I/O remain included
  • testing support remains included
  • game, graphics, audio, physics, and engine APIs remain excluded from the core library
  • specialized domain functionality remains in RETPAK packages
  • public APIs remain stable, typed, readable, and conservative

21. Summary

The Rethon standard library shall be general-purpose.

The core standard library shall include core types, primitive support, collections, iteration utilities, result and option types, error support, text utilities, numeric utilities, time and date, file and path APIs, basic I/O, async utilities, and testing support.

The standard library shall not include game, graphics, audio, physics, or engine-specific APIs, and Gamepenter integration shall remain outside the core distribution.

Specialized domain functionality shall be delivered through installable RETPAK packages.

The standard library shall remain stable, typed, readable, conservative, and compatible with the language's Python-first, protocol-oriented, value-oriented, and ownership-transparent design.