PyXDG

Warnings

• breaking PyXDG version 0.27 fixed compatibility issues with Python >= 3.8.4, specifically regarding menu processing. Older versions might encounter `AttributeError` or unexpected behavior.
  Fix: Upgrade to PyXDG 0.27 or newer.
• deprecated The `Rule.compile()` method in `xdg.Menu` was removed in PyXDG 0.24. Code relying on this method will break.
  Fix: Review `xdg.Menu` documentation for alternative methods for processing filter rules. The XML parsing was also reworked in 0.26.
• gotcha There is a known namespace collision with another package named `xdg` (which was later renamed to `xdg-base-dirs`). Installing both `pyxdg` and `xdg` (or `xdg-base-dirs`) might lead to import errors or unexpected behavior due to both trying to provide the `xdg` top-level package.
  Fix: If you explicitly need functionality from `xdg-base-dirs`, consider using virtual environments to isolate dependencies or ensure that only one of the packages providing the `xdg` namespace is installed in your environment. Prioritize `pyxdg` if you need the broader freedesktop.org standard implementations.
• gotcha The `xdg.BaseDirectory.get_runtime_dir()` method, when called with `strict=True` (the default), will not create the runtime directory if it doesn't exist or if permissions are incorrect, returning `None`. This can be a silent failure if not handled.
  Fix: Always check the return value of `get_runtime_dir()`. If a fallback or creation logic is desired, call it with `strict=False` (e.g., `BaseDirectory.get_runtime_dir(strict=False)`).
• gotcha When finding a file's MIME type, `xdg.Mime.get_type()` tries to use file contents and falls back to the name. If `name_pri` is set to 100 or higher, it prioritizes the filename. This can lead to incorrect MIME type detection if a file has a misleading extension and `name_pri` is not handled carefully.
  Fix: Be aware of the `name_pri` parameter in `xdg.Mime.get_type()`. If content-based detection is critical, ensure `name_pri` is set to a value less than 100 (its default behavior usually prioritizes content). For filename-only guessing, use `xdg.Mime.get_type_by_name()`.

Install

• pip install pyxdg Install PyXDG

Imports

• BaseDirectory

  from xdg import BaseDirectory

  PyXDG's modules are exposed under the 'xdg' top-level package.
• DesktopEntry

  from xdg import DesktopEntry

  PyXDG's modules are exposed under the 'xdg' top-level package.
• Mime

  from xdg import Mime

  PyXDG's modules are exposed under the 'xdg' top-level package.
• Menu

  from xdg import Menu

  PyXDG's modules are exposed under the 'xdg' top-level package.
• IconTheme

  from xdg import IconTheme

  PyXDG's modules are exposed under the 'xdg' top-level package.

Quickstart

This example demonstrates how to use `xdg.BaseDirectory` to get standard XDG paths and `xdg.Mime` to determine a file's MIME type.

import os
from xdg import BaseDirectory, Mime

# Get user's data home directory
data_home = BaseDirectory.xdg_data_home
print(f"XDG Data Home: {data_home}")

# Get preferred configuration directories
config_dirs = BaseDirectory.xdg_config_dirs
print(f"XDG Config Dirs: {config_dirs}")

# Find the MIME type of a file (example with a dummy file)
# Create a dummy file for demonstration
dummy_file_path = os.path.join(data_home, 'test.txt')
with open(dummy_file_path, 'w') as f:
    f.write('Hello, PyXDG!')

mime_type = Mime.get_type(dummy_file_path)
print(f"MIME type of '{dummy_file_path}': {mime_type}")

# Clean up dummy file
os.remove(dummy_file_path)