tessl/pypi-pysdl2

Pure Python wrapper around SDL2 libraries for cross-platform multimedia development

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

File I/O and Resource Loading

Name: tessl/pypi-pysdl2
Author: tessl

File I/O abstraction layer supporting files, memory buffers, and custom data sources through SDL_RWops. This system provides a unified interface for reading and writing data from various sources including files, memory, and network streams.

Capabilities

RWops Creation

Functions for creating SDL_RWops objects from different data sources.

def SDL_RWFromFile(file: bytes, mode: bytes) -> SDL_RWops:
    """
    Create an SDL_RWops structure from a file.
    
    Parameters:
    - file: file path as bytes
    - mode: file mode ("rb", "wb", "ab", etc.) as bytes
    
    Returns:
    SDL_RWops object or None on failure
    """

def SDL_RWFromMem(mem: bytes, size: int) -> SDL_RWops:
    """
    Create an SDL_RWops structure from a memory buffer (read/write).
    
    Parameters:
    - mem: memory buffer
    - size: buffer size in bytes
    
    Returns:
    SDL_RWops object or None on failure
    """

def SDL_RWFromConstMem(mem: bytes, size: int) -> SDL_RWops:
    """
    Create an SDL_RWops structure from a read-only memory buffer.
    
    Parameters:
    - mem: read-only memory buffer
    - size: buffer size in bytes
    
    Returns:
    SDL_RWops object or None on failure
    """

def SDL_AllocRW() -> SDL_RWops:
    """Allocate an empty, unpopulated SDL_RWops structure."""

def SDL_FreeRW(area: SDL_RWops) -> None:
    """Free an SDL_RWops structure allocated by SDL_AllocRW."""

File Operations

Core file I/O operations for reading, writing, and seeking.

def SDL_RWread(context: SDL_RWops, ptr: bytes, size: int, num: int) -> int:
    """
    Read from an SDL_RWops data source.
    
    Parameters:
    - context: SDL_RWops to read from
    - ptr: buffer to read data into
    - size: size of each data element
    - num: number of elements to read
    
    Returns:
    Number of elements read (may be less than requested on error/EOF)
    """

def SDL_RWwrite(context: SDL_RWops, ptr: bytes, size: int, num: int) -> int:
    """
    Write to an SDL_RWops data source.
    
    Parameters:
    - context: SDL_RWops to write to
    - ptr: buffer containing data to write
    - size: size of each data element  
    - num: number of elements to write
    
    Returns:
    Number of elements written
    """

def SDL_RWseek(context: SDL_RWops, offset: int, whence: int) -> int:
    """
    Seek to a position in an SDL_RWops data source.
    
    Parameters:
    - context: SDL_RWops to seek in
    - offset: byte offset from whence position
    - whence: seek reference point (RW_SEEK_SET, RW_SEEK_CUR, RW_SEEK_END)
    
    Returns:
    Final position in data source, or -1 on error
    """

def SDL_RWtell(context: SDL_RWops) -> int:
    """Get current position in SDL_RWops data source."""

def SDL_RWsize(context: SDL_RWops) -> int:
    """Get the size of the data source for an SDL_RWops."""

def SDL_RWclose(context: SDL_RWops) -> int:
    """
    Close and free an SDL_RWops structure.
    
    Parameters:
    - context: SDL_RWops to close
    
    Returns:
    0 on success, negative on error
    """

Endian-Aware Reading

Functions for reading data with specific byte order handling.

def SDL_ReadU8(src: SDL_RWops) -> int:
    """Read an unsigned 8-bit integer from SDL_RWops."""

def SDL_ReadLE16(src: SDL_RWops) -> int:
    """Read an unsigned 16-bit integer in little-endian format."""

def SDL_ReadBE16(src: SDL_RWops) -> int:
    """Read an unsigned 16-bit integer in big-endian format."""

def SDL_ReadLE32(src: SDL_RWops) -> int:
    """Read an unsigned 32-bit integer in little-endian format."""

def SDL_ReadBE32(src: SDL_RWops) -> int:
    """Read an unsigned 32-bit integer in big-endian format."""

def SDL_ReadLE64(src: SDL_RWops) -> int:
    """Read an unsigned 64-bit integer in little-endian format."""

def SDL_ReadBE64(src: SDL_RWops) -> int:
    """Read an unsigned 64-bit integer in big-endian format."""

Endian-Aware Writing

Functions for writing data with specific byte order handling.

def SDL_WriteU8(dst: SDL_RWops, value: int) -> int:
    """Write an unsigned 8-bit integer to SDL_RWops."""

def SDL_WriteLE16(dst: SDL_RWops, value: int) -> int:
    """Write an unsigned 16-bit integer in little-endian format."""

def SDL_WriteBE16(dst: SDL_RWops, value: int) -> int:
    """Write an unsigned 16-bit integer in big-endian format."""

def SDL_WriteLE32(dst: SDL_RWops, value: int) -> int:
    """Write an unsigned 32-bit integer in little-endian format."""

def SDL_WriteBE32(dst: SDL_RWops, value: int) -> int:
    """Write an unsigned 32-bit integer in big-endian format."""

def SDL_WriteLE64(dst: SDL_RWops, value: int) -> int:
    """Write an unsigned 64-bit integer in little-endian format."""

def SDL_WriteBE64(dst: SDL_RWops, value: int) -> int:
    """Write an unsigned 64-bit integer in big-endian format."""

Utility Functions

def SDL_LoadFile_RW(src: SDL_RWops, datasize: int, freesrc: int) -> bytes:
    """
    Load all data from an SDL_RWops data source.
    
    Parameters:
    - src: SDL_RWops to read from
    - datasize: pointer to store data size
    - freesrc: if non-zero, src is closed after loading
    
    Returns:
    Loaded data as bytes, or None on error
    """

Constants

# Seek reference points
RW_SEEK_SET = 0  # Seek from beginning of data
RW_SEEK_CUR = 1  # Seek relative to current position  
RW_SEEK_END = 2  # Seek relative to end of data

# RWops types
SDL_RWOPS_UNKNOWN = 0
SDL_RWOPS_WINFILE = 1
SDL_RWOPS_STDFILE = 2
SDL_RWOPS_JNIFILE = 3
SDL_RWOPS_MEMORY = 4
SDL_RWOPS_MEMORY_RO = 5

Usage Examples

Reading from Files

import sdl2

# Open file for reading
rw = sdl2.SDL_RWFromFile(b"data.bin", b"rb")
if rw:
    # Get file size
    file_size = sdl2.SDL_RWsize(rw)
    print(f"File size: {file_size} bytes")
    
    # Read data
    buffer = bytearray(file_size)
    bytes_read = sdl2.SDL_RWread(rw, buffer, 1, file_size)
    
    if bytes_read == file_size:
        print(f"Successfully read {bytes_read} bytes")
    
    # Close file
    sdl2.SDL_RWclose(rw)

Writing to Files

import sdl2

# Open file for writing
rw = sdl2.SDL_RWFromFile(b"output.bin", b"wb")
if rw:
    # Write data
    data = b"Hello, SDL2!"
    bytes_written = sdl2.SDL_RWwrite(rw, data, 1, len(data))
    
    if bytes_written == len(data):
        print(f"Successfully wrote {bytes_written} bytes")
    
    # Close file
    sdl2.SDL_RWclose(rw)

Memory Buffers

import sdl2

# Create RWops from memory buffer
data = b"Sample data in memory"
rw = sdl2.SDL_RWFromConstMem(data, len(data))

if rw:
    # Read from memory buffer
    buffer = bytearray(10)
    bytes_read = sdl2.SDL_RWread(rw, buffer, 1, 10)
    
    print(f"Read from memory: {buffer[:bytes_read]}")
    
    # Seek to different position
    sdl2.SDL_RWseek(rw, 7, sdl2.RW_SEEK_SET)
    
    # Read more data
    buffer2 = bytearray(4)
    bytes_read2 = sdl2.SDL_RWread(rw, buffer2, 1, 4)
    print(f"Read after seek: {buffer2[:bytes_read2]}")
    
    # Close RWops
    sdl2.SDL_RWclose(rw)

Endian-Aware Data Reading

import sdl2

# Open binary file containing numeric data
rw = sdl2.SDL_RWFromFile(b"numbers.dat", b"rb")
if rw:
    # Read various integer types
    byte_val = sdl2.SDL_ReadU8(rw)
    short_le = sdl2.SDL_ReadLE16(rw)  # Little-endian 16-bit
    int_be = sdl2.SDL_ReadBE32(rw)    # Big-endian 32-bit
    long_le = sdl2.SDL_ReadLE64(rw)   # Little-endian 64-bit
    
    print(f"Byte: {byte_val}")
    print(f"Short (LE): {short_le}")
    print(f"Int (BE): {int_be}")
    print(f"Long (LE): {long_le}")
    
    sdl2.SDL_RWclose(rw)

Loading Complete Files

import sdl2
from ctypes import c_size_t, pointer

# Load entire file into memory
rw = sdl2.SDL_RWFromFile(b"config.txt", b"rb")
if rw:
    # Load all data at once
    size = c_size_t()
    data = sdl2.SDL_LoadFile_RW(rw, pointer(size), 1)  # 1 = close RWops after loading
    
    if data:
        print(f"Loaded {size.value} bytes")
        # Process data...
        # Note: Remember to free the data when done

Types

class SDL_RWops:
    """
    File I/O abstraction structure for reading/writing data.
    
    Provides a unified interface for various data sources including
    files, memory buffers, and custom data streams.
    """

Install with Tessl CLI