Appdata Management Utilities

Common errors

• ModuleNotFoundError: No module named 'appdata.appdata_paths'

  cause Attempting to import the `AppdataPaths` class which was removed in `appdata` version 2.0.0.
  fix Update your import statement to `from appdata import AppData` and refactor your code to use the `AppData` class instead.

• TypeError: can only concatenate str (not "PosixPath") to str

  cause This error occurs when you try to concatenate a `pathlib.Path` object (returned by `appdata` v2.0+) with a string using the `+` operator.
  fix Use the `/` operator provided by `pathlib` for path concatenation (e.g., `my_path / 'filename.txt'`) or convert the `pathlib.Path` object to a string first using `str(my_path)`.

• AttributeError: type object 'AppData' has no attribute 'user_data_dir'

  cause You are trying to access instance attributes (like `user_data_dir`) directly on the `AppData` class without creating an instance first.
  fix First, create an instance of `AppData` by calling it with your application name and author (e.g., `app_data = AppData('MyApplication', 'MyCompany')`), then access the attributes on that instance (e.g., `app_data.user_data_dir`).

Warnings

• breaking The `AppdataPaths` class was completely removed in version 2.0.0. Its functionality was merged into the `AppData` class.
  Fix: Migrate your code to use the `AppData` class. For example, replace `from appdata.appdata_paths import AppdataPaths` with `from appdata import AppData` and create an instance of `AppData`.
• breaking In version 2.0.0, the methods `user_data_dir`, `user_config_dir`, `user_cache_dir`, `site_data_dir`, and `site_config_dir` (and their equivalents) now return `pathlib.Path` objects instead of strings.
  Fix: Update code that expects string results. `pathlib.Path` objects can be used directly for path manipulation (e.g., `path / 'filename.txt'`) or converted to strings using `str(path_object)` when interacting with APIs that require string paths.
• gotcha Attempting to concatenate a `pathlib.Path` object directly with a string using `+` will result in a `TypeError`.
  Fix: Use the `/` operator for concatenating `pathlib.Path` objects with strings or other `Path` objects, or explicitly convert the `Path` object to a string first using `str(path_object)` if string concatenation is absolutely necessary.

Install

• pip install appdata Install stable version

Imports

• AppData
  wrong:

  from appdata.appdata_paths import AppdataPaths

  correct:

  from appdata import AppData

  The `AppdataPaths` class was removed in version 2.0; use `AppData` instead, which consolidates its functionality.

Quickstart

This quickstart demonstrates how to initialize `AppData` for your application and access the common user data, configuration, and cache directories. It highlights that the library returns `pathlib.Path` objects, which are flexible for path manipulation and can be converted to strings when necessary.

import os
from appdata import AppData

# Replace 'MyAwesomeApp' and 'MyCompany' with your actual app/company names
APP_NAME = os.environ.get('APPDATA_APP_NAME', 'MyTestApp')
APP_AUTHOR = os.environ.get('APPDATA_APP_AUTHOR', 'MyTestCompany')

# Initialize AppData for your application
app_data = AppData(APP_NAME, APP_AUTHOR)

# Access common application directories
user_data_dir = app_data.user_data_dir
user_config_dir = app_data.user_config_dir
user_cache_dir = app_data.user_cache_dir

print(f"User Data Directory: {user_data_dir} (Type: {type(user_data_dir)})")
print(f"User Config Directory: {user_config_dir} (Type: {type(user_config_dir)})")
print(f"User Cache Directory: {user_cache_dir} (Type: {type(user_cache_dir)})")

# You can create subdirectories and files easily with pathlib.Path
some_file_path = user_data_dir / "settings.json"
print(f"Example file path using pathlib: {some_file_path}")

# To convert to string for older APIs if needed:
print(f"User data as string: {str(user_data_dir)}")