cmdkit.platform

Sensible default behavior for applications with platform-specific file paths.

Applications have a system, user, and local path. With respect to configuration files this ties in with the ideas implemented by Configuration. We want to allow for a cascade of files and environment variables. In addition to the site of configuration, applications have standard locations for any data they may need or create as well as a place for log files, telemetry, or tracebacks.

The AppContext data class holds these conventional paths and other context. The default() constructor builds these paths following platform-specific conventions.

Platform-Specific Paths

Assuming the following basic initialization, we initialize these file paths.

context = AppContext.default('MyApp', create_dirs=True, config_format='toml')

Windows

System

• context.path.system.lib: %PROGRAMDATA%\MyApp\Library

• context.path.system.log: %PROGRAMDATA%\MyApp\Logs

• context.path.system.config: %PROGRAMDATA%\MyApp\Config.toml

User

• context.path.user.lib: %APPDATA%\MyApp\Library

• context.path.user.log: %APPDATA%\MyApp\Logs

• context.path.user.config: %APPDATA%\MyApp\Config.toml

Local

• context.path.local.lib: %MYAPP_SITE%\Library

• context.path.local.log: %MYAPP_SITE%\Logs

• context.path.local.config: %MYAPP_SITE%\Config.toml

macOS

System

• context.path.system.lib: /Library/MyApp

• context.path.system.log: /Library/MyApp/Logs

• context.path.system.config: /Library/Preferences/MyApp/config.toml

User

• context.path.user.lib: $HOME/Library/MyApp

• context.path.user.log: $HOME/Library/MyApp/Logs

• context.path.user.config: $HOME/Library/Preferences/MyApp/config.toml

Local

• context.path.local.lib: $MYAPP_SITE/Library

• context.path.local.log: $MYAPP_SITE/Logs

• context.path.local.config: $MYAPP_SITE/config.toml

Linux / POSIX

System

• context.path.system.lib: /var/lib/myapp

• context.path.system.log: /var/log/myapp

• context.path.system.config: /etc/myapp.toml

User

• context.path.user.lib: $HOME/.myapp/lib

• context.path.user.log: $HOME/.myapp/log

• context.path.user.config: $HOME/.myapp/config.toml

Local

• context.path.local.lib: $MYAPP_SITE\lib

• context.path.local.log: $MYAPP_SITE\log

• context.path.local.config: $MYAPP_SITE\config.toml

If the environment variable MYAPP_SITE is not defined, the local site defaults to the .myapp in the current working directory.

---

Reference

class AppContext(cwd: str, home: str, name: str, is_admin: bool, default_site: str, default_path: Namespace, path: Namespace)

Runtime application context.

Defines filesystem paths for system, user, and local site. Depends on platform and whether runtime environment is admin or user space. The ‘default’ path mapping references the one identified by ‘default_site’.

classmethod default(name: str, create_dirs: bool = True, config_format: str = 'toml') → AppContext

Define default context with platform-specific paths.

If create_dirs=True, we create the default_site directies if needed. The default_site corresponds to the default_path extracted from path, and is local if the application site environment variable exists, otherwise user.

Available configuration formats are toml, yaml, and json.

cwd: str

The current working directory.

home: str

The user’s home directory (platform specific).

name: str

The application name (MyApp in the above example).

path: Namespace

A hierarchical Namespace mapping out file paths. Each of the members system, user, and local have keys lib (directory), log (directory) , and config (file).

default_site: str

Either local or user depending on whether the application site environment variable was defined.

default_path: Namespace

Section of path extracted by name depending on default_site.