libretro.py 0.0.0__py3-none-any.whl

libretro/__init__.py

@@ -0,0 +1,6 @@
+from .api import *
+from .builder import *
+from .core import *
+from .drivers import *
+from .error import *
+from .session import *

libretro/_utils.py

@@ -0,0 +1,388 @@
+import ctypes
+import sys
+from abc import abstractmethod
+from ctypes import POINTER, Union, c_char, c_char_p, cast
+from typing import Protocol, runtime_checkable
+
+from libretro.api._utils import c_uintptr
+
+if not hasattr(ctypes, "c_uintptr"):
+    ctypes._check_size(c_uintptr)
+
+
+class UserString:
+    def __init__(self, seq):
+        if isinstance(seq, bytes):
+            self.data = seq
+        elif isinstance(seq, UserString):
+            self.data = seq.data[:]
+        else:
+            self.data = str(seq).encode()
+
+    def __bytes__(self):
+        return self.data
+
+    def __str__(self):
+        return self.data.decode()
+
+    def __repr__(self):
+        return repr(self.data)
+
+    def __int__(self):
+        return int(self.data.decode())
+
+    def __long__(self):
+        return int(self.data.decode())
+
+    def __float__(self):
+        return float(self.data.decode())
+
+    def __complex__(self):
+        return complex(self.data.decode())
+
+    def __hash__(self):
+        return hash(self.data)
+
+    def __le__(self, string):
+        if isinstance(string, UserString):
+            return self.data <= string.data
+        else:
+            return self.data <= string
+
+    def __lt__(self, string):
+        if isinstance(string, UserString):
+            return self.data < string.data
+        else:
+            return self.data < string
+
+    def __ge__(self, string):
+        if isinstance(string, UserString):
+            return self.data >= string.data
+        else:
+            return self.data >= string
+
+    def __gt__(self, string):
+        if isinstance(string, UserString):
+            return self.data > string.data
+        else:
+            return self.data > string
+
+    def __eq__(self, string):
+        if isinstance(string, UserString):
+            return self.data == string.data
+        else:
+            return self.data == string
+
+    def __ne__(self, string):
+        if isinstance(string, UserString):
+            return self.data != string.data
+        else:
+            return self.data != string
+
+    def __contains__(self, char):
+        return char in self.data
+
+    def __len__(self):
+        return len(self.data)
+
+    def __getitem__(self, index):
+        return self.__class__(self.data[index])
+
+    def __getslice__(self, start, end):
+        start = max(start, 0)
+        end = max(end, 0)
+        return self.__class__(self.data[start:end])
+
+    def __add__(self, other):
+        if isinstance(other, UserString):
+            return self.__class__(self.data + other.data)
+        elif isinstance(other, bytes):
+            return self.__class__(self.data + other)
+        else:
+            return self.__class__(self.data + str(other).encode())
+
+    def __radd__(self, other):
+        if isinstance(other, bytes):
+            return self.__class__(other + self.data)
+        else:
+            return self.__class__(str(other).encode() + self.data)
+
+    def __mul__(self, n):
+        return self.__class__(self.data * n)
+
+    __rmul__ = __mul__
+
+    def __mod__(self, args):
+        return self.__class__(self.data % args)
+
+    # the following methods are defined in alphabetical order:
+    def capitalize(self):
+        return self.__class__(self.data.capitalize())
+
+    def center(self, width, *args):
+        return self.__class__(self.data.center(width, *args))
+
+    def count(self, sub, start=0, end=sys.maxsize):
+        return self.data.count(sub, start, end)
+
+    def decode(self, encoding=None, errors=None):  # XXX improve this?
+        if encoding:
+            if errors:
+                return self.__class__(self.data.decode(encoding, errors))
+            else:
+                return self.__class__(self.data.decode(encoding))
+        else:
+            return self.__class__(self.data.decode())
+
+    def encode(self, encoding=None, errors=None):  # XXX improve this?
+        if encoding:
+            if errors:
+                return self.__class__(self.data.encode(encoding, errors))
+            else:
+                return self.__class__(self.data.encode(encoding))
+        else:
+            return self.__class__(self.data.encode())
+
+    def endswith(self, suffix, start=0, end=sys.maxsize):
+        return self.data.endswith(suffix, start, end)
+
+    def expandtabs(self, tabsize=8):
+        return self.__class__(self.data.expandtabs(tabsize))
+
+    def find(self, sub, start=0, end=sys.maxsize):
+        return self.data.find(sub, start, end)
+
+    def index(self, sub, start=0, end=sys.maxsize):
+        return self.data.index(sub, start, end)
+
+    def isalpha(self):
+        return self.data.isalpha()
+
+    def isalnum(self):
+        return self.data.isalnum()
+
+    def isdecimal(self):
+        return self.data.isdecimal()
+
+    def isdigit(self):
+        return self.data.isdigit()
+
+    def islower(self):
+        return self.data.islower()
+
+    def isnumeric(self):
+        return self.data.isnumeric()
+
+    def isspace(self):
+        return self.data.isspace()
+
+    def istitle(self):
+        return self.data.istitle()
+
+    def isupper(self):
+        return self.data.isupper()
+
+    def join(self, seq):
+        return self.data.join(seq)
+
+    def ljust(self, width, *args):
+        return self.__class__(self.data.ljust(width, *args))
+
+    def lower(self):
+        return self.__class__(self.data.lower())
+
+    def lstrip(self, chars=None):
+        return self.__class__(self.data.lstrip(chars))
+
+    def partition(self, sep):
+        return self.data.partition(sep)
+
+    def replace(self, old, new, maxsplit=-1):
+        return self.__class__(self.data.replace(old, new, maxsplit))
+
+    def rfind(self, sub, start=0, end=sys.maxsize):
+        return self.data.rfind(sub, start, end)
+
+    def rindex(self, sub, start=0, end=sys.maxsize):
+        return self.data.rindex(sub, start, end)
+
+    def rjust(self, width, *args):
+        return self.__class__(self.data.rjust(width, *args))
+
+    def rpartition(self, sep):
+        return self.data.rpartition(sep)
+
+    def rstrip(self, chars=None):
+        return self.__class__(self.data.rstrip(chars))
+
+    def split(self, sep=None, maxsplit=-1):
+        return self.data.split(sep, maxsplit)
+
+    def rsplit(self, sep=None, maxsplit=-1):
+        return self.data.rsplit(sep, maxsplit)
+
+    def splitlines(self, keepends=0):
+        return self.data.splitlines(keepends)
+
+    def startswith(self, prefix, start=0, end=sys.maxsize):
+        return self.data.startswith(prefix, start, end)
+
+    def strip(self, chars=None):
+        return self.__class__(self.data.strip(chars))
+
+    def swapcase(self):
+        return self.__class__(self.data.swapcase())
+
+    def title(self):
+        return self.__class__(self.data.title())
+
+    def translate(self, *args):
+        return self.__class__(self.data.translate(*args))
+
+    def upper(self):
+        return self.__class__(self.data.upper())
+
+    def zfill(self, width):
+        return self.__class__(self.data.zfill(width))
+
+
+class MutableString(UserString):
+    """mutable string objects
+
+    Python strings are immutable objects.  This has the advantage, that
+    strings may be used as dictionary keys.  If this property isn't needed
+    and you insist on changing string values in place instead, you may cheat
+    and use MutableString.
+
+    But the purpose of this class is an educational one: to prevent
+    people from inventing their own mutable string class derived
+    from UserString and than forget thereby to remove (override) the
+    __hash__ method inherited from UserString.  This would lead to
+    errors that would be very hard to track down.
+
+    A faster and better solution is to rewrite your program using lists."""
+
+    def __init__(self, string=""):
+        self.data = string
+
+    def __hash__(self):
+        raise TypeError("unhashable type (it is mutable)")
+
+    def __setitem__(self, index, sub):
+        if index < 0:
+            index += len(self.data)
+        if index < 0 or index >= len(self.data):
+            raise IndexError
+        self.data = self.data[:index] + sub + self.data[index + 1 :]
+
+    def __delitem__(self, index):
+        if index < 0:
+            index += len(self.data)
+        if index < 0 or index >= len(self.data):
+            raise IndexError
+        self.data = self.data[:index] + self.data[index + 1 :]
+
+    def __setslice__(self, start, end, sub):
+        start = max(start, 0)
+        end = max(end, 0)
+        if isinstance(sub, UserString):
+            self.data = self.data[:start] + sub.data + self.data[end:]
+        elif isinstance(sub, bytes):
+            self.data = self.data[:start] + sub + self.data[end:]
+        else:
+            self.data = self.data[:start] + str(sub).encode() + self.data[end:]
+
+    def __delslice__(self, start, end):
+        start = max(start, 0)
+        end = max(end, 0)
+        self.data = self.data[:start] + self.data[end:]
+
+    def immutable(self):
+        return UserString(self.data)
+
+    def __iadd__(self, other):
+        if isinstance(other, UserString):
+            self.data += other.data
+        elif isinstance(other, bytes):
+            self.data += other
+        else:
+            self.data += str(other).encode()
+        return self
+
+    def __imul__(self, n):
+        self.data *= n
+        return self
+
+
+class String(MutableString, Union):
+    _fields_ = [("raw", POINTER(c_char)), ("data", c_char_p)]
+
+    def __init__(self, obj=b""):
+        if isinstance(obj, (bytes, UserString)):
+            self.data = bytes(obj)
+        else:
+            self.raw = obj
+
+    def __len__(self):
+        return self.data and len(self.data) or 0
+
+    def from_param(cls, obj):
+        # Convert None or 0
+        if obj is None or obj == 0:
+            return cls(POINTER(c_char)())
+
+        # Convert from String
+        elif isinstance(obj, String):
+            return obj
+
+        # Convert from bytes
+        elif isinstance(obj, bytes):
+            return cls(obj)
+
+        # Convert from str
+        elif isinstance(obj, str):
+            return cls(obj.encode())
+
+        # Convert from c_char_p
+        elif isinstance(obj, c_char_p):
+            return obj
+
+        # Convert from POINTER(ctypes.c_char)
+        elif isinstance(obj, POINTER(c_char)):
+            return obj
+
+        # Convert from raw pointer
+        elif isinstance(obj, int):
+            return cls(cast(obj, POINTER(c_char)))
+
+        # Convert from ctypes.c_char array
+        elif isinstance(obj, c_char * len(obj)):
+            return obj
+
+        # Convert from object
+        else:
+            return String.from_param(obj._as_parameter_)
+
+    from_param = classmethod(from_param)
+
+
+def ReturnString(obj, func=None, arguments=None):
+    return String.from_param(obj)
+
+
+def ord_if_char(value):
+    """
+    Simple helper used for casts to simple builtin types:  if the argument is a
+    string type, it will be converted to it's ordinal value.
+
+    This function will raise an exception if the argument is string with more
+    than one characters.
+    """
+    return ord(value) if (isinstance(value, bytes) or isinstance(value, str)) else value
+
+
+@runtime_checkable
+class Pollable(Protocol):
+    @abstractmethod
+    def poll(self) -> None:
+        ...

libretro/api/__init__.py

@@ -0,0 +1,52 @@
+"""
+This module contains types that directly correspond to the libretro API.
+
+All ``retro_`` classes in this package are ctypes wrappers around their equivalents in
+`libretro-common <https://github.com/libretro/RetroArch/blob/master/libretro-common/include/libretro.h>`_.
+
+Unless otherwise noted, all structs can be copied with ``copy.deepcopy``;
+the struct itself and its fields (including strings and buffers) are all deep-copied.
+For example:
+
+.. code-block:: python
+
+        import copy
+        from libretro.api import retro_controller_description
+
+        desc = retro_controller_description(b'Game Pad', 5)
+        desc_copy = copy.deepcopy(desc)
+
+        assert desc == desc_copy
+
+        desc.desc = b'Another Game Pad'
+        assert desc != desc_copy
+
+Additionally, all `c_char_p` fields are converted to Python `bytes` objects when accessed.
+"""
+
+from .audio import *
+from .av import *
+from .camera import *
+from .content import *
+from .disk import *
+from .environment import *
+from .input import *
+from .led import *
+from .location import *
+from .log import *
+from .memory import *
+from .message import *
+from .microphone import *
+from .midi import *
+from .netpacket import *
+from .options import *
+from .perf import *
+from .power import *
+from .proc import *
+from .rumble import *
+from .savestate import *
+from .sensor import *
+from .timing import *
+from .user import *
+from .vfs import *
+from .video import *

libretro/api/_utils.py

@@ -0,0 +1,172 @@
+import ctypes
+import mmap
+from collections.abc import Buffer, Iterator
+from contextlib import contextmanager
+from copy import deepcopy
+from ctypes import (
+    POINTER,
+    Array,
+    Structure,
+    addressof,
+    c_char_p,
+    c_double,
+    c_int,
+    c_int16,
+    c_int32,
+    c_int64,
+    c_size_t,
+    c_ssize_t,
+    c_ubyte,
+    c_uint8,
+    c_void_p,
+    cast,
+    py_object,
+    pythonapi,
+    sizeof,
+)
+from os import PathLike
+from typing import TypeAlias, get_type_hints
+
+# When https://github.com/python/cpython/issues/112015 is merged,
+# use ctypes.memoryview_at instead of this hack
+# taken from https://stackoverflow.com/a/72968176/1089957
+pythonapi.PyMemoryView_FromMemory.argtypes = (c_char_p, c_ssize_t, c_int)
+pythonapi.PyMemoryView_FromMemory.restype = py_object
+
+_int_types = (c_int16, c_int32)
+if hasattr(ctypes, "c_int64"):
+    # Some builds of ctypes apparently do not have ctypes.c_int64
+    # defined; it's a pretty good bet that these builds do not
+    # have 64-bit pointers.
+    _int_types += (c_int64,)
+for t in _int_types:
+    if sizeof(t) == sizeof(c_size_t):
+        c_ptrdiff_t = t
+del t
+del _int_types
+
+
+# From https://blag.nullteilerfrei.de/2021/06/20/prettier-struct-definitions-for-python-ctypes
+# Please use it for all future struct definitions
+class FieldsFromTypeHints(type(Structure)):
+    def __new__(cls, name, bases, namespace):
+        class AnnotationDummy:
+            __annotations__ = namespace.get("__annotations__", {})
+
+        annotations = get_type_hints(AnnotationDummy)
+        namespace["_fields_"] = list(annotations.items())
+        namespace["__slots__"] = list(annotations.keys())
+        return type(Structure).__new__(cls, name, bases, namespace)
+
+
+def as_bytes(value: str | bytes | None) -> bytes | None:
+    if isinstance(value, str):
+        return value.encode("utf-8")
+    return value
+
+
+def is_zeroed(struct: Structure) -> bool:
+    view = memoryview_at(addressof(struct), sizeof(struct), True)
+
+    return not any(view)
+
+
+def from_zero_terminated[S](ptr) -> Iterator[S]:
+    if ptr:
+        i = 0
+        while not is_zeroed(ptr[i]):
+            yield ptr[i]
+            i += 1
+
+
+Pointer: TypeAlias = ctypes._Pointer
+
+
+def deepcopy_array(array: Pointer, length: int, memo):
+    if not array:
+        return None
+
+    arraytype: type[Array] = array._type_ * length
+    return arraytype(*(deepcopy(array[i], memo) for i in range(length)))
+
+
+def deepcopy_buffer(ptr: c_void_p | int, size: int) -> c_void_p | None:
+    if ptr is not None and not isinstance(ptr, (c_void_p, int)):
+        raise TypeError(f"Expected c_void_p or int, got {type(ptr).__name__}")
+
+    if not ptr:
+        return None
+
+    if not size:
+        return None
+
+    arraytype: type[Array] = c_uint8 * size
+    data = arraytype.from_buffer_copy(c_void_p(ptr))
+    return cast(data, c_void_p)
+
+
+@contextmanager
+def mmap_file(path: str | PathLike, mode: str = "rb"):
+    with open(path, mode, buffering=0) as f:
+        with mmap.mmap(f.fileno(), 0, access=mmap.ACCESS_COPY) as m:
+            view = memoryview(m)
+            yield view
+            view.release()
+            # If we don't release the memoryview manually,
+            # we'll get a BufferError when the context manager exits
+        f.close()
+
+
+def addressof_buffer(buffer: Buffer) -> int:
+    if not isinstance(buffer, Buffer):
+        raise TypeError(f"Expected Buffer, got {type(buffer).__name__}")
+    array_type: type[Array] = c_ubyte * len(buffer)
+    buffer_array = array_type.from_buffer(buffer)
+
+    return ctypes.addressof(buffer_array)
+
+
+def memoryview_at(
+    address: c_char_p | c_void_p | int, size: c_ssize_t | int, readonly=False
+) -> memoryview:
+    flags = c_int(0x100 if readonly else 0x200)
+    return pythonapi.PyMemoryView_FromMemory(cast(address, c_char_p), c_ssize_t(size), flags)
+
+
+class c_uintptr(ctypes._SimpleCData):
+    _type_ = "P"
+
+
+c_double_p = POINTER(c_double)
+
+
+# As of ctypes 1.0, ctypes does not support custom error-checking
+# functions on callbacks, nor does it support custom datatypes on
+# callbacks, so we must ensure that all callbacks return
+# primitive datatypes.
+#
+# Non-primitive return values wrapped with UNCHECKED won't be
+# typechecked, and will be converted to ctypes.c_void_p.
+def UNCHECKED(type):
+    if hasattr(type, "_type_") and isinstance(type._type_, str) and type._type_ != "P":
+        return type
+    else:
+        return c_void_p
+
+
+__all__ = [
+    "FieldsFromTypeHints",
+    "as_bytes",
+    "is_zeroed",
+    "from_zero_terminated",
+    "Pointer",
+    "deepcopy_array",
+    "deepcopy_buffer",
+    "mmap_file",
+    "addressof_buffer",
+    "memoryview_at",
+    "c_ptrdiff_t",
+    "c_uintptr",
+    "c_double_p",
+    "UNCHECKED",
+]

libretro/api/audio.py

@@ -0,0 +1,42 @@
+from ctypes import CFUNCTYPE, POINTER, Structure, c_bool, c_int16, c_size_t, c_uint
+from dataclasses import dataclass
+
+from libretro.api._utils import FieldsFromTypeHints
+
+retro_audio_sample_t = CFUNCTYPE(None, c_int16, c_int16)
+retro_audio_sample_batch_t = CFUNCTYPE(c_size_t, POINTER(c_int16), c_size_t)
+retro_audio_callback_t = CFUNCTYPE(None)
+retro_audio_set_state_callback_t = CFUNCTYPE(None, c_bool)
+retro_audio_buffer_status_callback_t = CFUNCTYPE(None, c_bool, c_uint, c_bool)
+
+
+@dataclass
+class retro_audio_callback(Structure, metaclass=FieldsFromTypeHints):
+    callback: retro_audio_callback_t
+    set_state: retro_audio_set_state_callback_t
+
+    def __deepcopy__(self, _):
+        return retro_audio_callback(callback=self.callback, set_state=self.set_state)
+
+
+@dataclass
+class retro_audio_buffer_status_callback(Structure, metaclass=FieldsFromTypeHints):
+    callback: retro_audio_buffer_status_callback_t
+
+    def __call__(self, active: bool, occupancy: int, underrun_likely: bool) -> None:
+        if self.callback:
+            self.callback(active, occupancy, underrun_likely)
+
+    def __deepcopy__(self, _):
+        return retro_audio_buffer_status_callback(callback=self.callback)
+
+
+__all__ = [
+    "retro_audio_sample_t",
+    "retro_audio_sample_batch_t",
+    "retro_audio_callback_t",
+    "retro_audio_set_state_callback_t",
+    "retro_audio_buffer_status_callback_t",
+    "retro_audio_callback",
+    "retro_audio_buffer_status_callback",
+]