{"id":8527,"library":"pystow","title":"PyStow","description":"PyStow is a Python library that simplifies the process of picking a consistent and predictable location for storing data generated or consumed by your Python code. It helps manage application data directories and ensures their existence, often defaulting to a structured `$HOME/.data/<app_name>` path. The current version is 0.8.3, and it maintains an active development and release cadence, with version 0.8.4-dev also documented.","status":"active","version":"0.8.3","language":"en","source_language":"en","source_url":"https://github.com/cthoyt/pystow.git","tags":["data management","file system","caching","pathlib","data storage","utilities"],"install":[{"cmd":"pip install pystow","lang":"bash","label":"Install PyStow"}],"dependencies":[{"reason":"Required for `ensure_csv`, `ensure_excel`, `load_df`, and other DataFrame-related I/O utilities.","package":"pandas","optional":true},{"reason":"Used for XDG Base Directory Specification compatibility when `PYSTOW_USE_APPDIRS` is enabled.","package":"platformdirs","optional":true}],"imports":[{"symbol":"pystow","correct":"import pystow"}],"quickstart":{"code":"import pystow\nimport os\n\n# Configure a custom base directory for PyStow (optional, for testing/isolation)\n# Defaults to ~/.data if not set\nos.environ['PYSTOW_HOME'] = os.path.join(os.getcwd(), 'my_pystow_data')\n\n# Get a directory for your application data\napp_dir = pystow.join('my_app')\nprint(f\"Application data directory: {app_dir}\")\napp_dir.mkdir(parents=True, exist_ok=True)\n\n# Ensure a file is downloaded from a URL into a specific subdirectory\nurl = 'https://raw.githubusercontent.com/pykeen/pykeen/master/src/pykeen/datasets/nations/test.txt'\nfile_path = pystow.ensure(\n    'my_app', 'datasets', 'nations', \n    url=url,\n    name='nations_test.txt'\n)\nprint(f\"Ensured file path: {file_path}\")\n\n# You can also use modules for cleaner access\nmy_app_module = pystow.module('my_app')\nmodule_file_path = my_app_module.ensure(\n    'another_data', \n    url='https://example.com/some_file.txt', \n    name='some_file.txt' # This URL is a placeholder and will likely fail.\n)\nprint(f\"Ensured file via module: {module_file_path}\")\n\n# Clean up the custom directory for demonstration\n# import shutil\n# if os.path.exists(os.environ['PYSTOW_HOME']):\n#     shutil.rmtree(os.environ['PYSTOW_HOME'])\n# del os.environ['PYSTOW_HOME']","lang":"python","description":"This quickstart demonstrates how to use `pystow.join` to get and create application-specific directories, and `pystow.ensure` to download and store a file, ensuring its presence. It also shows the `pystow.module` pattern. A temporary custom `PYSTOW_HOME` is set for isolated testing, which defaults to `$HOME/.data` if not configured."},"warnings":[{"fix":"To control the base directory, set `PYSTOW_HOME` environment variable (e.g., `os.environ['PYSTOW_HOME'] = '/path/to/data'`) or `PYSTOW_USE_APPDIRS='True'` for XDG compliance. Ensure your application explicitly checks or sets these if a specific data location is critical.","message":"PyStow defaults to storing data in `$HOME/.data/`. This can be overridden globally by setting the `PYSTOW_HOME` environment variable, or by enabling XDG compatibility with `PYSTOW_USE_APPDIRS=True`, which uses `appdirs` or `platformdirs`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"There is no direct fix for users within the library. If strict type checking is required for your project, you might need to add `pystow` to `mypy`'s `[mypy-pystow*]` section with `ignore_missing_imports = True` in your `mypy.ini` or similar configuration.","message":"As of version 0.8.3, PyStow does not ship with a `py.typed` file, leading to `mypy` and other static type checkers skipping its analysis and reporting 'missing library stubs or py.typed marker' errors.","severity":"gotcha","affected_versions":"<=0.8.3"},{"fix":"Always explicitly define the `name` argument in `pystow.ensure` if you have a specific filename expectation, especially for URLs that might not have a clean filename component. Review the resulting `Path` object to confirm the filename is as expected.","message":"When using `pystow.ensure`, especially with `name` argument, be aware that the `name` overrides the filename derived from the URL. If the URL does not have a proper filename, `name` is essential, but if it does, `name` changes it. Ensure the `name` matches your expectation for the downloaded file.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Add `ignore_missing_imports = True` for `pystow` in your `mypy` configuration (e.g., in `mypy.ini` under `[mypy-pystow*]`) to suppress this error and allow `mypy` to continue checking the rest of your project.","cause":"PyStow does not currently include a `py.typed` file in its distribution, which is necessary for static type checkers like `mypy` to properly analyze the library's types.","error":"Skipping analyzing \"pystow\": module is installed, but missing library stubs or py.typed marker"},{"fix":"Ensure that `pystow.join()` or `pystow.module()` calls are properly made, which automatically create directories. Verify that the `PYSTOW_HOME` environment variable (if set) points to a valid and writable location. Check application logs for any `pystow`-related path resolution issues.","cause":"The application is trying to access a file or directory managed by PyStow, but PyStow's base directory or a specific subdirectory was not created, or an environment variable (like `PYSTOW_HOME`) is pointing to a non-existent or inaccessible location.","error":"FileNotFoundError: [Errno 2] No such file or directory: '/some/unexpected/path/my_app/data.txt'"}]}