{"id":4230,"library":"pyxdg","title":"PyXDG","description":"PyXDG is a Python library that provides implementations of various freedesktop.org standards. These standards define common desktop operations and components, such as determining file MIME types, getting icons for applications, and accessing application menus. It is currently at version 0.28 and is actively maintained, with releases addressing compatibility and bug fixes.","status":"active","version":"0.28","language":"en","source_language":"en","source_url":"https://github.com/takluyver/pyxdg","tags":["freedesktop","xdg","desktop environment","mime types","base directory","linux"],"install":[{"cmd":"pip install pyxdg","lang":"bash","label":"Install PyXDG"}],"dependencies":[],"imports":[{"note":"PyXDG's modules are exposed under the 'xdg' top-level package.","symbol":"BaseDirectory","correct":"from xdg import BaseDirectory"},{"note":"PyXDG's modules are exposed under the 'xdg' top-level package.","symbol":"DesktopEntry","correct":"from xdg import DesktopEntry"},{"note":"PyXDG's modules are exposed under the 'xdg' top-level package.","symbol":"Mime","correct":"from xdg import Mime"},{"note":"PyXDG's modules are exposed under the 'xdg' top-level package.","symbol":"Menu","correct":"from xdg import Menu"},{"note":"PyXDG's modules are exposed under the 'xdg' top-level package.","symbol":"IconTheme","correct":"from xdg import IconTheme"}],"quickstart":{"code":"import os\nfrom xdg import BaseDirectory, Mime\n\n# Get user's data home directory\ndata_home = BaseDirectory.xdg_data_home\nprint(f\"XDG Data Home: {data_home}\")\n\n# Get preferred configuration directories\nconfig_dirs = BaseDirectory.xdg_config_dirs\nprint(f\"XDG Config Dirs: {config_dirs}\")\n\n# Find the MIME type of a file (example with a dummy file)\n# Create a dummy file for demonstration\ndummy_file_path = os.path.join(data_home, 'test.txt')\nwith open(dummy_file_path, 'w') as f:\n    f.write('Hello, PyXDG!')\n\nmime_type = Mime.get_type(dummy_file_path)\nprint(f\"MIME type of '{dummy_file_path}': {mime_type}\")\n\n# Clean up dummy file\nos.remove(dummy_file_path)\n","lang":"python","description":"This example demonstrates how to use `xdg.BaseDirectory` to get standard XDG paths and `xdg.Mime` to determine a file's MIME type."},"warnings":[{"fix":"Upgrade to PyXDG 0.27 or newer.","message":"PyXDG version 0.27 fixed compatibility issues with Python >= 3.8.4, specifically regarding menu processing. Older versions might encounter `AttributeError` or unexpected behavior.","severity":"breaking","affected_versions":"<0.27"},{"fix":"Review `xdg.Menu` documentation for alternative methods for processing filter rules. The XML parsing was also reworked in 0.26.","message":"The `Rule.compile()` method in `xdg.Menu` was removed in PyXDG 0.24. Code relying on this method will break.","severity":"deprecated","affected_versions":"<0.24"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions when `xdg` or `xdg-base-dirs` are also installed"},{"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)`).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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()`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}