App Paths¶
A mechanism for obtaining platform-appropriate file system locations for an application.
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.