GitHub

user_directories

API reference for user_directories.

Where a program keeps its files per user (Effect's effect/persistence/UserDirectories). Provide user_directories.layer; platform.layer doesn't include it (nor does Effect's NodeServices)::

@fx.fn
def config_dir():
    dirs = yield from UserDirectories()
    return (yield from dirs.config("myapp"))   # ~/.config/myapp on Linux

path = fx.run_blocking(config_dir().pipe(fx.provide(user_directories.layer)))

An absolute XDG_CONFIG_HOME / XDG_DATA_HOME / XDG_CACHE_HOME / XDG_STATE_HOME wins on every platform. Otherwise macOS uses ~/Library/Application Support (~/Library/Caches for the cache), Windows APPDATA / LOCALAPPDATA (or AppData under USERPROFILE, the cache in a Cache folder), and other systems the XDG defaults. The variables are read from the ConfigProvider on every call.

Re-exports

Values

AttributeTypeDescription
layerLayer[UserDirectories]

The host's directories.

Types

TypeDefinitionDescription
Kindtype Kind = Literal['config', 'data', 'cache', 'state']

Classes

Functions

make

make(*, platform=None) -> UserDirectoriesService

The directories by platform's rules ("linux", "darwin", "win32", ...; default: sys.platform).

ParameterTypeDescription
platformstr | None = None

Returns UserDirectoriesService

def make(*, platform: str | None = None) -> UserDirectoriesService:
    """The directories by ``platform``'s rules (``"linux"``, ``"darwin"``,
    ``"win32"``, ...; default: ``sys.platform``)."""
    name = sys.platform if platform is None else platform
    home_variable = "USERPROFILE" if name == "win32" else "HOME"

    def optional_string(variable: str) -> config.Config[str | None]:
        return config.string(variable).with_default(None)

    def read[A](method: str, source: config.Config[A]) -> Effect[A, PlatformError]:
        return source.map_error(
            lambda cause: system_error(
                "Unknown",
                module="UserDirectories",
                method=method,
                description="Failed to read the environment",
                cause=cause,
            )
        )

    def not_found(method: str) -> PlatformError:
        return system_error(
            "NotFound",
            module="UserDirectories",
            method=method,
            description=f"{home_variable} is not set",
        )

    def directory(kind: Kind) -> Callable[[str], Effect[str, PlatformError]]:
        app_data = "APPDATA" if kind in ("config", "data") else "LOCALAPPDATA"
        environment = config.all(
            optional_string(home_variable), optional_string(_XDG[kind]), optional_string(app_data)
        ).map(lambda values: _Environment(*values))

        def resolve(app_name: str) -> Effect[str, PlatformError]:
            def found(env: _Environment) -> Effect[str, PlatformError]:
                resolved = _resolve(name, kind, app_name, env)
                return fail(not_found(kind)) if resolved is None else succeed(resolved)

            return read(kind, environment).flat_map(found)

        return resolve

    def home(found: str | None) -> Effect[str, PlatformError]:
        return fail(not_found("home")) if found is None else succeed(found)

    return UserDirectoriesService(
        home=read("home", optional_string(home_variable)).flat_map(home),
        config=directory("config"),
        data=directory("data"),
        cache=directory("cache"),
        state=directory("state"),
    )

layer_platform

layer_platform(platform) -> Layer[UserDirectories]

platform's directories.

ParameterTypeDescription
platformstr

Returns Layer[UserDirectories]

def layer_platform(platform: str) -> Layer[UserDirectories]:
    """``platform``'s directories."""
    return layer_sync(UserDirectories, lambda: make(platform=platform))