libretro.py 0.2.0__tar.gz → 0.3.0__tar.gz

{libretro_py-0.2.0 → libretro_py-0.3.0}/CHANGELOG.md

@@ -10,6 +10,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 > breaking changes may be introduced
 > at any time without warning.
 
+## [0.3.0] - 2024-09-25
+
+### Added
+
+- Add `TempDirPathDriver`.
+- Added various runnable scripts for test purposes.
+- Add a new guide for taking a capture with RenderDoc.
+- Add labels to OpenGL objects created by `ModernGlVideoDriver`.
+- Add debug groups to important methods within `ModernGlVideoDriver`.
+
+### Changed
+
+- **BREAKING:** Rename `DefaultPathDriver` to `ExplicitPathDriver`.
+- Make `TempDirPathDriver` the default path driver used by `SessionBuilder`.
+
+### Fixed
+
+- Improved documentation for parts of `SessionBuilder` and `VideoDriver`
+- Removed a `glClear` call in `ModernGlVideoDriver` that was left in by accident.
+- Clear the `glGetError` queue at various places in `ModernGlVideoDriver`
+  to prevent PyOpenGL from misreporting errors that came from moderngl or the loaded core.
+
+### Removed
+
+- **BREAKING:** Remove `VideoDriverInitArgs`.
+
 ## [0.2.0] - 2024-09-12
 
 Thanks to @JSensebe for his contributions!

{libretro_py-0.2.0/src/libretro.py.egg-info → libretro_py-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: libretro.py
-Version: 0.2.0
+Version: 0.3.0
 Summary: A libretro frontend for Python intended for testing cores.
 Author-email: Jesse Talavera <jesse@jesse.tg>
 Maintainer-email: Jesse Talavera <jesse@jesse.tg>

{libretro_py-0.2.0 → libretro_py-0.3.0}/src/libretro/api/video/context.py

@@ -36,6 +36,7 @@ class HardwareContext(IntEnum):
     D3D11 = RETRO_HW_CONTEXT_D3D11
     D3D10 = RETRO_HW_CONTEXT_D3D10
     D3D12 = RETRO_HW_CONTEXT_D3D12
+    D3D9 = RETRO_HW_CONTEXT_D3D9
 
     def __init__(self, value):
         self._type_ = "I"

{libretro_py-0.2.0 → libretro_py-0.3.0}/src/libretro/builder.py

@@ -16,23 +16,21 @@ from libretro.api import (
     ThrottleMode,
     retro_device_power,
     retro_game_info,
-    retro_hw_render_callback,
     retro_throttle_state,
 )
 from libretro.core import Core
 from libretro.drivers import (
     ArrayAudioDriver,
-    ArrayVideoDriver,
     AudioDriver,
     CompositeEnvironmentDriver,
     ConstantPowerDriver,
     ContentDriver,
-    DefaultPathDriver,
     DefaultPerfDriver,
     DefaultTimingDriver,
     DefaultUserDriver,
     DictLedDriver,
     DictOptionDriver,
+    DriverMap,
     FileSystemInterface,
     GeneratorInputDriver,
     GeneratorLocationDriver,
@@ -57,31 +55,30 @@ from libretro.drivers import (
     PowerDriver,
     StandardContentDriver,
     StandardFileSystemInterface,
+    TempDirPathDriver,
     TimingDriver,
     UnformattedLogDriver,
     UserDriver,
     VideoDriver,
-    VideoDriverInitArgs,
 )
 from libretro.session import Session
 
-try:
-    from libretro.drivers.video import ModernGlVideoDriver
-except ImportError:
-    ModernGlVideoDriver = None
-
 
 class _DefaultType(Enum):
     DEFAULT = auto()
 
 
 DEFAULT = _DefaultType.DEFAULT
-Default = Literal[_DefaultType.DEFAULT]
 """
-A placeholder that indicates the default value for a SessionBuilder argument.
-When passed to a SessionBuilder method, the method will use the default value for that argument.
+A placeholder that indicates the default value for one of :obj:`SessionBuilder`'s arguments.
+When passed to one of :obj:`.SessionBuilder`'s ``with_`` methods,
+it will use the default driver or argument configuration
+unless otherwise noted.
 """
 
+Default: TypeAlias = Literal[_DefaultType.DEFAULT]
+
+
 T = TypeVar("T")
 
 _RequiredFactory: TypeAlias = Callable[[], T]
@@ -100,7 +97,7 @@ InputDriverArg: TypeAlias = (
     | InputStateIterator
     | Default
 )
-VideoDriverArg: TypeAlias = _RequiredArg[VideoDriver] | Default
+VideoDriverArg: TypeAlias = _RequiredArg[VideoDriver] | DriverMap | Default
 ContentArg: TypeAlias = (
     Content | SubsystemContent | _OptionalFactory[Content | SubsystemContent] | None
 )
@@ -110,7 +107,7 @@ MessageDriverArg: TypeAlias = _OptionalArg[MessageInterface] | Logger
 OptionDriverArg: TypeAlias = (
     _OptionalArg[OptionDriver] | Mapping[AnyStr, AnyStr] | Literal[0, 1, 2]
 )
-PathDriverArg: TypeAlias = _OptionalArg[PathDriver] | str | PathLike
+PathDriverArg: TypeAlias = PathDriver | Callable[[Core], PathDriver | None] | Default | None
 LogDriverArg: TypeAlias = _OptionalArg[LogDriver] | Logger
 PerfDriverArg: TypeAlias = _OptionalArg[PerfDriver]
 LocationDriverArg: TypeAlias = _OptionalArg[LocationDriver] | LocationInputGenerator
@@ -146,7 +143,7 @@ class _SessionBuilderArgs(TypedDict):
     overscan: _OptionalFactory[bool]  # TODO: Replace with some driver (not sure what yet)
     message: _OptionalFactory[MessageInterface]
     options: _OptionalFactory[OptionDriver]
-    path: _OptionalFactory[PathDriver]
+    path: Callable[[Core], PathDriver | None]
     log: _OptionalFactory[LogDriver]
     perf: _OptionalFactory[PerfDriver]
     location: _OptionalFactory[LocationDriver]
@@ -168,13 +165,23 @@ class _SessionBuilderArgs(TypedDict):
 
 class SessionBuilder:
     """
-    A builder class for constructing Session objects.
+    A builder class for constructing a :py:class:`.Session`.
 
-    A Session requires a Core, an AudioDriver, an InputDriver, and a VideoDriver;
-    each ``with_`` method sets an argument (mostly drivers) for the Session.
+    At minimum, a :py:class:`.Session` requires a :py:class:`.Core`,
+    an :py:class:`.AudioDriver`,
+    an :py:class:`.InputDriver`,
+    and a :py:class:`.VideoDriver`;
+    each ``with_`` method sets an argument (mostly drivers) for the :py:class:`.Session`.
     """
 
     def __init__(self):
+        """
+        Initializes a new :py:class:`SessionBuilder` with no arguments,
+        not even the required ones.
+
+        Calling :py:meth:`build` before setting any of the required arguments
+        will raise a :py:class:`RequiredError`.
+        """
         self._args = _SessionBuilderArgs(
             core=lambda: _raise_required_error("A Core is required"),
             audio=lambda: _raise_required_error("An AudioDriver is required"),
@@ -185,7 +192,7 @@ class SessionBuilder:
             overscan=_nothing,
             message=_nothing,
             options=_nothing,
-            path=_nothing,
+            path=lambda _: None,
             log=_nothing,
             perf=_nothing,
             location=_nothing,
@@ -203,23 +210,33 @@ class SessionBuilder:
             power=_nothing,
         )
 
+    @classmethod
+    def defaults(cls, core: CoreArg) -> Self:
+        """
+        Alias to :py:func:`defaults`.
+        """
+        return defaults(core)
+
     def with_core(self, core: CoreArg) -> Self:
         """
         Sets the core to use for the session.
 
-        ``core`` may be one of the following:
+        :param core: The core to use for the session. May be one of the following:
+
+            :class:`.Core`
+                Will be used as-is.
+
+            :class:`str`, :class:`~os.PathLike`
+                Will load a :class:`.Core` from this path in :meth:`build`.
 
-        - A :class:`Core` that will be used as-is.
-        - A :class:`str` or :class:`PathLike` that represents a path to the core.
-          It will be loaded as a :class:`Core` when the session is built.
-        - A :class:`CDLL` object that represents a loaded binary.
-          It will be loaded into a :class:`Core` when the session is built.
-        - A :class:`Callable` that returns one of the above types.
-          It will be evaluated when the session is built.
+            :class:`~ctypes.CDLL`
+                Will load a :class:`.Core` from this library in :meth:`build`.
 
-        :param core: The core to use for the session.
-        :return: This builder object.
-        :raises ValueError: If ``core`` is :py:const:`Default`.
+            :class:`~collections.abc.Callable` () -> :class:`.Core`
+                Zero-argument function that returns a :class:`.Core`.
+                Will be called in :meth:`build`.
+
+        :return: This :class:`SessionBuilder` object.
         :raises TypeError: If ``core`` is not one of the permitted types.
         """
         match core:
@@ -229,11 +246,9 @@ class SessionBuilder:
                 self._args["core"] = lambda: core
             case str() | PathLike() | CDLL():
                 self._args["core"] = lambda: Core(core)
-            case _DefaultType.DEFAULT:
-                raise ValueError("Core does not have a default value")
             case _:
                 raise TypeError(
-                    f"Expected Core, str, PathLike, a CDLL, or a callable that returns one of them; got {type(core).__name__}"
+                    f"Expected Core, str, PathLike, a CDLL, or a callable that returns a Core; got {type(core).__name__}"
                 )
 
         return self
@@ -241,10 +256,38 @@ class SessionBuilder:
     def with_content(self, content: ContentArg) -> Self:
         """
         Sets the content to use for this session.
+        Will be loaded and managed by this builder's assigned :class:`.ContentDriver`.
+
+        :param content: The content to use for this session. May be one of the following:
 
-        ``content`` may be one of the following:
+            :class:`str`, :class:`~os.PathLike`
+                Will load a single content file without enabling a subsystem.
 
-        TODO
+            :class:`zipfile.Path`
+                Will load a single content file within a ZIP archive without enabling a subsystem.
+
+            :class:`bytes`, :class:`bytearray`, :class:`memoryview`, :class:`~collections.abc.Buffer`
+                Will expose a single unnamed content buffer without enabling a subsystem.
+
+            :class:`.SubsystemContent`
+                Will enable a subsystem and load multiple associated content files.
+
+            :class:`.retro_game_info`
+                Will be passed to the core as-is without enabling a subsystem.
+
+            :obj:`None`
+                Will load the core without using any content or enabling a subsystem;
+                if not supported by the core, this will raise an error in :meth:`build`.
+                Note that ``retro_load_game`` **will** be called.
+
+            :class:`~collections.abc.Callable` () -> :data:`.Content` | :class:`.SubsystemContent` | :obj:`None`
+                Zero-argument function that returns one of the above.
+                Will be called in :meth:`build`.
+
+        :return: This :class:`.SessionBuilder` object.
+        :raises TypeError: If ``content`` is not one of the permitted types.
+
+        :see: :meth:`.ContentDriver.load` for details on how loaded content is exposed to the core.
         """
         match content:
             case Callable() as func:
@@ -326,20 +369,26 @@ class SessionBuilder:
         """
         Sets the video driver for this session.
 
-        The default video driver is a ``MultiVideoDriver`` that supports the following contexts:
+        :param video: The video driver to use for this session. May be one of the following:
 
-        - ``HardwareContext.NONE``: An ``ArrayVideoDriver``.
-        - ``HardwareContext.OPENGL``: A ``ModernGlVideoDriver`` if the ``moderngl`` package is installed,
-          absent if not.
+            :class:`.VideoDriver`
+                Used by the built :class:`.Session` as-is.
 
-        :param video: One of the following:
+            :const:`DEFAULT`
+                Uses a :class:`.MultiVideoDriver` with its default configuration.
+                See its documentation for more details.
 
-            - A ``VideoDriver`` that will be used as-is.
-            - A ``Callable`` that returns a ``VideoDriver``.
-            - A :class:`Callable` that returns a :class:`VideoDriver`.
-            - :py:const:`DEFAULT` to use the default video driver.
-            - :py:const:`None` to raise an error.
-        :return: This builder object.
+            :class:`~collections.abc.Mapping` [:class:`.HardwareContext`, :class:`~collections.abc.Callable` () -> :class:`.VideoDriver`]
+                Uses a :class:`.MultiVideoDriver` with the provided driver map.
+
+            :class:`~collections.abc.Callable` () -> :class:`.VideoDriver`
+                Zero-argument function that returns a :class:`.VideoDriver`.
+                Called in :meth:`build`.
+
+
+        :return: This :class:`SessionBuilder` object.
+        :raises TypeError: If ``video`` is not one of the aforementioned types.
+        :raises ValueError: If ``video`` does not contain a mapping for :attr:`.HardwareContext.NONE`.
         """
 
         match video:
@@ -348,20 +397,28 @@ class SessionBuilder:
             case VideoDriver():
                 self._args["video"] = lambda: video
             case _DefaultType.DEFAULT:
-                drivers: dict[HardwareContext, Callable[[], VideoDriver]] = dict()
-                drivers[HardwareContext.NONE] = ArrayVideoDriver
+                self._args["video"] = MultiVideoDriver
+            case Mapping():
+                if HardwareContext.NONE not in video:
+                    raise ValueError("A driver for HardwareContext.NONE is required")
+
+                if not all(isinstance(k, HardwareContext) for k in video.keys()):
+                    raise TypeError(
+                        "Each key in the provided driver map must be a HardwareContext"
+                    )
 
-                if ModernGlVideoDriver:
-                    # If moderngl is installed...
-                    drivers[HardwareContext.OPENGL] = ModernGlVideoDriver
-                    drivers[HardwareContext.OPENGL_CORE] = ModernGlVideoDriver
+                if not all(callable(v) for v in video.values()):
+                    raise TypeError(
+                        "Each value in the provided driver map must be a callable that returns a VideoDriver"
+                    )
+
+                self._args["video"] = lambda: MultiVideoDriver(video)
 
-                self._args["video"] = lambda: MultiVideoDriver(drivers)
             case None:
                 raise ValueError("A video driver is required")
             case _:
                 raise TypeError(
-                    f"Expected a VideoDriver, a callable that returns one, or DEFAULT; got {type(video).__name__}"
+                    f"Expected a VideoDriver, a callable that returns one, a map of HardwareContexts to Callables, or DEFAULT; got {type(video).__name__}"
                 )
 
         return self
@@ -420,6 +477,41 @@ class SessionBuilder:
         return self
 
     def with_options(self, options: OptionDriverArg) -> Self:
+        """
+        Configures the options driver for this session.
+
+        :param options: May be one of the following:
+
+            :class:`.OptionDriver`
+                Will be used by the built :class:`.Session` as-is.
+
+            :class:`~collections.abc.Mapping` [:obj:`~typing.AnyStr`, :obj:`~typing.AnyStr`]
+                Will be used to initialize a :class:`.DictOptionDriver` with the provided options
+                and with API version 2.
+                All keys and values must be either :class:`str` or :class:`bytes`;
+                mixing the two is not allowed.
+
+            ``0``, ``1``, or ``2``
+                Will be used to initialize a :class:`.DictOptionDriver` with no initial options
+                using the provided API version.
+
+            :data:`.DEFAULT`
+                Will use a :class:`.DictOptionDriver` with API version 2
+                and no initial options.
+
+            :obj:`None`
+                All environment calls that :class:`.OptionDriver` normally implements
+                will be unavailable to the loaded :class:`.Core`.
+
+            :class:`~collections.abc.Callable` () -> :class:`.OptionDriver` | :obj:`None`
+                Zero-argument function that returns an :class:`.OptionDriver` or :obj:`None`.
+                Will be called in :meth:`build`.
+
+        :return: This :class:`.SessionBuilder` object.
+        :raises TypeError: If ``options`` is not one of the aforementioned types.
+        :raises ValueError: If ``options`` is a :class:`~collections.abc.Mapping` whose keys and values
+            are not all :class:`str` or :class:`bytes`.
+        """
         _types = (str, bytes)
         match options:
             case Callable() as func:
@@ -427,11 +519,17 @@ class SessionBuilder:
             case OptionDriver() as driver:
                 driver: OptionDriver
                 self._args["options"] = lambda: driver
-            case dict(vars) if all(
-                isinstance(k, _types) and isinstance(v, _types) for k, v in vars.items()
-            ):
-                vars: Mapping[AnyStr, AnyStr]
-                self._args["options"] = lambda: DictOptionDriver(2, True, vars)
+            case Mapping() as optionvars:
+                optionvars: Mapping[AnyStr, AnyStr]
+                all_str = all(
+                    isinstance(k, str) and isinstance(v, str) for k, v in optionvars.items()
+                )
+                all_bytes = all(
+                    isinstance(k, bytes) and isinstance(v, bytes) for k, v in optionvars.items()
+                )
+                if not (all_str or all_bytes):
+                    raise ValueError("All keys and values must be either str or bytes")
+                self._args["options"] = lambda: DictOptionDriver(2, True, optionvars)
             case 0 | 1 | 2 as version:
                 self._args["options"] = lambda: DictOptionDriver(version)
             case _DefaultType.DEFAULT:
@@ -440,21 +538,46 @@ class SessionBuilder:
                 self._args["options"] = _nothing
             case _:
                 raise TypeError(
-                    f"Expected OptionDriver, a dict, a callable that returns one, DEFAULT, or None; got {type(options).__name__}"
+                    f"Expected an OptionDriver, a Mapping, DEFAULT, an API version, or a Callable that returns an OptionDriver, or None; got {type(options).__name__}"
                 )
 
         return self
 
     def with_paths(self, path: PathDriverArg) -> Self:
+        """
+        Configures the path driver for this session.
+
+        :param path: May be one of the following:
+
+            :class:`.PathDriver`
+                Will be used by the built :class:`.Session` as-is.
+
+            :data:`.DEFAULT`
+                Will use a :class:`.TempDirPathDriver`
+                configured with an unspecified temporary directory
+                and the provided :class:`.Core`'s path.
+
+            :class:`~collections.abc.Callable` (:class:`.Core`) -> :class:`.PathDriver` | :obj:`None`
+                One-argument function that accepts a :class:`.Core`
+                and returns a :class:`.PathDriver` or :obj:`None`.
+                Will be called in :meth:`build` with the configured :class:`.Core` as the argument.
+
+            :obj:`None`
+                All environment calls that :class:`.PathDriver` normally implements
+                will be unavailable to the loaded :class:`.Core`.
+
+        :return: This :class:`.SessionBuilder` object.
+        :raises TypeError: If ``path`` is not one of the aforementioned types.
+        """
         match path:
             case Callable() as func:
                 self._args["path"] = func
             case PathDriver():
-                self._args["path"] = lambda: path
+                self._args["path"] = lambda _: path
             case _DefaultType.DEFAULT:
-                self._args["path"] = DefaultPathDriver  # TODO: How to pass core path?
+                self._args["path"] = lambda core: TempDirPathDriver(core)
             case None:
-                self._args["path"] = _nothing
+                self._args["path"] = lambda _: None
             case _:
                 raise TypeError(
                     f"Expected PathDriver, a callable that returns one, DEFAULT, or None; got {type(path).__name__}"
@@ -742,7 +865,12 @@ class SessionBuilder:
 
     def build(self) -> Session:
         """
-        Constructs a Session object with the provided arguments.
+        Constructs a :py:class:`.Session` with the provided arguments.
+
+        :raises RequiredError: If a :py:class:`.Core`, :py:class:`.AudioDriver`, :py:class:`.InputDriver`, or :py:class:`.VideoDriver` is not set.
+        :raises Exception: Any exception raised by a registered driver factory or initializer.
+
+        :return: A :py:class:`.Session` object.
         """
         core = self._args["core"]()
         content = self._args["content"]()
@@ -754,7 +882,7 @@ class SessionBuilder:
             overscan=self._args["overscan"](),
             message=self._args["message"](),
             options=self._args["options"](),
-            path=self._args["path"](),
+            path=self._args["path"](core),
             log=self._args["log"](),
             perf=self._args["perf"](),
             location=self._args["location"](),
@@ -777,6 +905,19 @@ class SessionBuilder:
 
 
 def defaults(core: CoreArg) -> SessionBuilder:
+    """
+    Constructs a :py:class:`SessionBuilder` with the recommended drivers and their default values.
+    Does not build the session, so these defaults may still be overridden.
+
+    :param core: The core to use for the session.
+
+    Examples::
+
+        builder = SessionBuilder.defaults(core)
+        with builder.with_log(None).build() as session:
+            pass
+
+    """
     return (
         SessionBuilder()
         .with_core(core)
@@ -810,4 +951,5 @@ __all__ = [
     "SessionBuilder",
     "DEFAULT",
     "defaults",
+    "RequiredError",
 ]

{libretro_py-0.2.0 → libretro_py-0.3.0}/src/libretro/drivers/content/standard.py

@@ -92,6 +92,8 @@ class StandardContentDriver(ContentDriver):
             raise RuntimeError("System info not set")
 
         with ExitStack() as stack:
+            # We may be loading several files, each of which needs its own context manager
+            # So we use ExitStack to manage all of their lives at once
             loaded_content: Sequence[LoadedContentFile | None] | None
             subsystem: retro_subsystem_info | None = None
             match content:
@@ -273,12 +275,12 @@ class StandardContentDriver(ContentDriver):
                 yield LoadedContentFile(loaded_info, loaded_info_ext)
 
             # For test cases that provide content by path
-            case str(path) | PathLike(path), ContentAttributes(need_fullpath=True):
+            case (str() | PathLike()) as path, ContentAttributes(need_fullpath=True):
                 loaded_info = retro_game_info(os.fsencode(path), None, 0, None)
                 loaded_info_ext = _make_game_info_ext(loaded_info)
                 yield LoadedContentFile(loaded_info, loaded_info_ext)
                 # There's no data to persist, so no cleanup needed
-            case str(path) | PathLike(path), ContentAttributes(persistent_data=False):
+            case (str() | PathLike()) as path, ContentAttributes(persistent_data=False):
                 with mmap_file(path) as view:
                     loaded_info = retro_game_info(
                         os.fsencode(path), addressof_buffer(view), len(view), None
@@ -286,7 +288,7 @@ class StandardContentDriver(ContentDriver):
                     loaded_info_ext = _make_game_info_ext(loaded_info)
                     yield LoadedContentFile(loaded_info, loaded_info_ext)
                     # Content is not persistent, so just let the with statement clean up the view
-            case str(path) | PathLike(path), ContentAttributes(persistent_data=True):
+            case (str() | PathLike()) as path, ContentAttributes(persistent_data=True):
                 context = mmap_file(path)
                 view = context.__enter__()
                 loaded_info = retro_game_info(

{libretro_py-0.2.0 → libretro_py-0.3.0}/src/libretro/drivers/path/__init__.py

@@ -2,5 +2,6 @@
 Drivers that determine the paths and directories associated with the core.
 """
 
-from .default import *
 from .driver import *
+from .explicit import *
+from .temp import *

libretro_py-0.3.0/src/libretro/drivers/path/driver.py

@@ -0,0 +1,64 @@
+from abc import abstractmethod
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class PathDriver(Protocol):
+    """
+    Interface for a driver that defines various paths exposed to libretro cores.
+    """
+
+    @property
+    @abstractmethod
+    def system_dir(self) -> bytes | None:
+        """
+        Corresponds to :py:attr:`.EnvironmentCall.GET_SYSTEM_DIRECTORY`.
+
+        If :py:obj:`None`, a core's call to ``RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY`` should return ``false``.
+        """
+        ...
+
+    @property
+    @abstractmethod
+    def libretro_path(self) -> bytes | None:
+        """
+        Corresponds to :py:attr:`.EnvironmentCall.GET_LIBRETRO_PATH`.
+
+        If :py:obj:`None`, a core's call to ``RETRO_ENVIRONMENT_GET_LIBRETRO_PATH`` should return ``false``.
+        """
+        ...
+
+    @property
+    @abstractmethod
+    def core_assets_dir(self) -> bytes | None:
+        """
+        Corresponds to :py:attr:`.EnvironmentCall.GET_CORE_ASSETS_DIRECTORY`.
+
+        If :py:obj:`None`, a core's call to ``RETRO_ENVIRONMENT_GET_CORE_ASSETS_DIRECTORY`` should return ``false``.
+        """
+        ...
+
+    @property
+    @abstractmethod
+    def save_dir(self) -> bytes | None:
+        """
+        Corresponds to :py:attr:`.EnvironmentCall.GET_SAVE_DIRECTORY`.
+
+        If :py:obj:`None`, a core's call to ``RETRO_ENVIRONMENT_GET_SAVE_DIRECTORY`` should return ``false``.
+        """
+        ...
+
+    @property
+    @abstractmethod
+    def playlist_dir(self) -> bytes | None:
+        """
+        Corresponds to :py:attr:`.EnvironmentCall.GET_PLAYLIST_DIRECTORY`.
+
+        If :py:obj:`None`, a core's call to ``RETRO_ENVIRONMENT_GET_PLAYLIST_DIRECTORY`` should return ``false``.
+        """
+        ...
+
+
+__all__ = [
+    "PathDriver",
+]