PyStow

Common errors

• Skipping analyzing "pystow": module is installed, but missing library stubs or py.typed marker

  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.
  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.

• FileNotFoundError: [Errno 2] No such file or directory: '/some/unexpected/path/my_app/data.txt'

  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.
  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.

Warnings

• gotcha 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`.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• pip install pystow Install PyStow

Imports

• pystow

  import pystow

Quickstart

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.

import pystow
import os

# Configure a custom base directory for PyStow (optional, for testing/isolation)
# Defaults to ~/.data if not set
os.environ['PYSTOW_HOME'] = os.path.join(os.getcwd(), 'my_pystow_data')

# Get a directory for your application data
app_dir = pystow.join('my_app')
print(f"Application data directory: {app_dir}")
app_dir.mkdir(parents=True, exist_ok=True)

# Ensure a file is downloaded from a URL into a specific subdirectory
url = 'https://raw.githubusercontent.com/pykeen/pykeen/master/src/pykeen/datasets/nations/test.txt'
file_path = pystow.ensure(
    'my_app', 'datasets', 'nations', 
    url=url,
    name='nations_test.txt'
)
print(f"Ensured file path: {file_path}")

# You can also use modules for cleaner access
my_app_module = pystow.module('my_app')
module_file_path = my_app_module.ensure(
    'another_data', 
    url='https://example.com/some_file.txt', 
    name='some_file.txt' # This URL is a placeholder and will likely fail.
)
print(f"Ensured file via module: {module_file_path}")

# Clean up the custom directory for demonstration
# import shutil
# if os.path.exists(os.environ['PYSTOW_HOME']):
#     shutil.rmtree(os.environ['PYSTOW_HOME'])
# del os.environ['PYSTOW_HOME']