or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/pypi-appdirs

A small Python module for determining appropriate platform-specific dirs, e.g. a "user data dir".

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/appdirs@1.4.x

To install, run

npx @tessl/cli install tessl/pypi-appdirs@1.4.0

index.mddocs/

Appdirs

A small Python module for determining appropriate platform-specific directories for storing application data, configuration files, cache data, and logs. It implements the XDG Base Directory Specification for Unix systems while providing native directory conventions for Windows and macOS.

Package Information

  • Package Name: appdirs
  • Language: Python
  • Installation: pip install appdirs

Core Imports

import appdirs

Or import specific functions:

from appdirs import user_data_dir, user_config_dir, AppDirs

Basic Usage

import appdirs

# Get platform-appropriate directories for your app
data_dir = appdirs.user_data_dir("MyApp", "MyCompany")
config_dir = appdirs.user_config_dir("MyApp", "MyCompany") 
cache_dir = appdirs.user_cache_dir("MyApp", "MyCompany")

print(f"Data directory: {data_dir}")
print(f"Config directory: {config_dir}")
print(f"Cache directory: {cache_dir}")

# Using the convenience class
dirs = appdirs.AppDirs("MyApp", "MyCompany", version="1.0")
print(f"User data: {dirs.user_data_dir}")
print(f"User config: {dirs.user_config_dir}")
print(f"User cache: {dirs.user_cache_dir}")

Capabilities

User Data Directory

Returns the user-specific data directory path for an application, following platform conventions.

def user_data_dir(appname=None, appauthor=None, version=None, roaming=False):
    """
    Return full path to the user-specific data dir for this application.

    Args:
        appname (str, optional): Name of application. If None, just the system directory is returned.
        appauthor (str, optional): Name of the appauthor or distributing body (Windows only). 
                                 Typically the owning company name. Falls back to appname. 
                                 You may pass False to disable it.
        version (str, optional): Optional version path element to append to the path.
                               Typically "<major>.<minor>". Only applied when appname is present.
        roaming (bool): Can be set True to use the Windows roaming appdata directory.

    Returns:
        str: Full path to user data directory

    Platform examples:
        Mac OS X: ~/Library/Application Support/<AppName>
        Unix: ~/.local/share/<AppName> (or in $XDG_DATA_HOME, if defined)
        Windows: C:\\Users\\<username>\\AppData\\Local\\<AppAuthor>\\<AppName>
    """

Site Data Directory

Returns the system-wide shared data directory path for an application.

def site_data_dir(appname=None, appauthor=None, version=None, multipath=False):
    """
    Return full path to the user-shared data dir for this application.

    Args:
        appname (str, optional): Name of application. If None, just the system directory is returned.
        appauthor (str, optional): Name of the appauthor or distributing body (Windows only).
        version (str, optional): Optional version path element to append to the path.
        multipath (bool): Parameter only applicable to *nix which indicates that the entire 
                         list of data dirs should be returned. By default, the first item 
                         from XDG_DATA_DIRS is returned.

    Returns:
        str: Full path to site data directory (or path separator-joined paths if multipath=True)

    Platform examples:
        Mac OS X: /Library/Application Support/<AppName>
        Unix: /usr/local/share/<AppName> or /usr/share/<AppName>
        Windows: C:\\ProgramData\\<AppAuthor>\\<AppName>
        
    Warning:
        Do not use this on Windows. See Vista compatibility issues in documentation.
    """

User Config Directory

Returns the user-specific config directory path for an application.

def user_config_dir(appname=None, appauthor=None, version=None, roaming=False):
    """
    Return full path to the user-specific config dir for this application.

    Args:
        appname (str, optional): Name of application. If None, just the system directory is returned.
        appauthor (str, optional): Name of the appauthor or distributing body (Windows only).
        version (str, optional): Optional version path element to append to the path.
        roaming (bool): Can be set True to use the Windows roaming appdata directory.

    Returns:
        str: Full path to user config directory

    Platform examples:
        Mac OS X: same as user_data_dir
        Unix: ~/.config/<AppName> (or in $XDG_CONFIG_HOME, if defined)
        Windows: same as user_data_dir
    """

Site Config Directory

Returns the system-wide shared config directory path for an application.

def site_config_dir(appname=None, appauthor=None, version=None, multipath=False):
    """
    Return full path to the user-shared config dir for this application.

    Args:
        appname (str, optional): Name of application. If None, just the system directory is returned.
        appauthor (str, optional): Name of the appauthor or distributing body (Windows only).
        version (str, optional): Optional version path element to append to the path.
        multipath (bool): Parameter only applicable to *nix which indicates that the entire 
                         list of config dirs should be returned.

    Returns:
        str: Full path to site config directory (or path separator-joined paths if multipath=True)

    Platform examples:
        Mac OS X: same as site_data_dir
        Unix: /etc/xdg/<AppName> or $XDG_CONFIG_DIRS[i]/<AppName>
        Windows: same as site_data_dir
        
    Warning:
        Do not use this on Windows. See Vista compatibility issues in documentation.
    """

User Cache Directory

Returns the user-specific cache directory path for an application.

def user_cache_dir(appname=None, appauthor=None, version=None, opinion=True):
    """
    Return full path to the user-specific cache dir for this application.

    Args:
        appname (str, optional): Name of application. If None, just the system directory is returned. 
        appauthor (str, optional): Name of the appauthor or distributing body (Windows only).
        version (str, optional): Optional version path element to append to the path.
        opinion (bool): Can be False to disable the appending of "Cache" to the base app 
                       data dir for Windows.

    Returns:
        str: Full path to user cache directory

    Platform examples:
        Mac OS X: ~/Library/Caches/<AppName>
        Unix: ~/.cache/<AppName> (XDG default)
        Windows: C:\\Users\\<username>\\AppData\\Local\\<AppAuthor>\\<AppName>\\Cache
    """

User State Directory

Returns the user-specific state directory path for an application.

def user_state_dir(appname=None, appauthor=None, version=None, roaming=False):
    """
    Return full path to the user-specific state dir for this application.

    Args:
        appname (str, optional): Name of application. If None, just the system directory is returned.
        appauthor (str, optional): Name of the appauthor or distributing body (Windows only).
        version (str, optional): Optional version path element to append to the path.
        roaming (bool): Can be set True to use the Windows roaming appdata directory.

    Returns:
        str: Full path to user state directory

    Platform examples:
        Mac OS X: same as user_data_dir
        Unix: ~/.local/state/<AppName> (or in $XDG_STATE_HOME, if defined)
        Windows: same as user_data_dir
    """

User Log Directory

Returns the user-specific log directory path for an application.

def user_log_dir(appname=None, appauthor=None, version=None, opinion=True):
    """
    Return full path to the user-specific log dir for this application.

    Args:
        appname (str, optional): Name of application. If None, just the system directory is returned.
        appauthor (str, optional): Name of the appauthor or distributing body (Windows only).  
        version (str, optional): Optional version path element to append to the path.
        opinion (bool): Can be False to disable the appending of "Logs" to the base app 
                       data dir for Windows, and "log" to the base cache dir for Unix.

    Returns:
        str: Full path to user log directory

    Platform examples:
        Mac OS X: ~/Library/Logs/<AppName>
        Unix: ~/.cache/<AppName>/log (or under $XDG_CACHE_HOME if defined)
        Windows: C:\\Users\\<username>\\AppData\\Local\\<AppAuthor>\\<AppName>\\Logs
    """

AppDirs Class

Convenience wrapper class for getting application directories with consistent configuration.

class AppDirs:
    """
    Convenience wrapper for getting application dirs.
    
    Args:
        appname (str, optional): Application name
        appauthor (str, optional): Application author/company  
        version (str, optional): Version path element
        roaming (bool): Use Windows roaming profiles
        multipath (bool): Return all paths on Unix systems
    """
    
    def __init__(self, appname=None, appauthor=None, version=None, roaming=False, multipath=False):
        """Initialize AppDirs with application metadata."""
    
    @property
    def user_data_dir(self):
        """User data directory path."""
    
    @property  
    def site_data_dir(self):
        """Site data directory path."""
    
    @property
    def user_config_dir(self):
        """User config directory path."""
    
    @property
    def site_config_dir(self):
        """Site config directory path."""
    
    @property
    def user_cache_dir(self):
        """User cache directory path."""
    
    @property
    def user_state_dir(self):
        """User state directory path."""
    
    @property
    def user_log_dir(self):
        """User log directory path."""

Version Information

__version__: str  # Package version string (e.g., "1.4.4")
__version_info__: tuple  # Version info as tuple of integers

Platform Constants

PY3: bool  # True if running Python 3, False otherwise
system: str  # Platform identifier string (win32, darwin, linux2, etc.)