App Paths

A mechanism for obtaining platform-appropriate file system locations for an application.

Availability (Key)

macOS

GTK

Windows

iOS

Android

Web

Terminal

Usage

When Python code executes from the command line, the working directory is a known location - the location where the application was started. However, when executing GUI apps, the working directory varies between platforms. As a result, when specifying file paths, relative paths cannot be used, as there is no location to which they can be considered relative.

Complicating matters further, operating systems have conventions (and in some cases, hard restrictions) over where certain file types should be stored. For example, macOS provides the ~/Library/Application Support folder; Linux encourages use of the ~/.config folder (amongst others), and Windows provides the AppData/Local folder in the user’s home directory. Application sandbox and security policies will sometimes prevent reading or writing files in any location other than these pre-approved locations.

To assist with finding an appropriate location to store application files, every Toga application instance has a paths attribute that returns an instance of Paths. This object provides known file system locations that are appropriate for storing files of given types, such as configuration files, log files, cache files, or user data.

Each location provided by the Paths object is a pathlib.Path that can be used to construct a full file path. If required, additional sub-folders can be created under these locations.

You should not assume that any of these paths already exist. The location is guaranteed to follow operating system conventions, but the application is responsible for ensuring the folder exists prior to writing files in these locations.

Reference

class toga.paths.Paths
property app: Path

The path of the folder that contains the definition of the app class.

This path should be considered read-only. You should not attempt to write files into this path.

property cache: Path

The platform-appropriate location for storing cache files associated with this app.

It should be assumed that the operating system will purge the contents of this directory without warning if it needs to recover disk space.

property config: Path

The platform-appropriate location for storing user configuration files associated with this app.

property data: Path

The platform-appropriate location for storing user data associated with this app.

property logs: Path

The platform-appropriate location for storing log files associated with this app.

property toga: Path

The path that contains the core Toga resources.

This path should be considered read-only. You should not attempt to write files into this path.