oschmod: Cross-platform file permissions

Common errors

• FileNotFoundError: [Errno 2] No such file or directory: 'non_existent_file.txt'

  cause The path provided to `oschmod` does not point to an existing file or directory.
  fix Verify that the `file_path` argument is correct and that the file or directory exists at that location before calling `oschmod`.

• PermissionError: [Errno 13] Permission denied: 'some_protected_file.txt'

  cause The Python process does not have sufficient privileges to modify the permissions of the specified file or directory.
  fix Run your Python script with elevated permissions (e.g., as an administrator on Windows, or using `sudo` on Linux/macOS), or ensure the current user has ownership/write permissions to the target path.

• AttributeError: module 'oschmod' has no attribute 'chmod'

  cause You are trying to call `oschmod.chmod()` but the main function within the `oschmod` module for changing permissions is also named `oschmod`.
  fix Call `oschmod.oschmod(path, mode)` instead of `oschmod.chmod(path, mode)`. If you used `import oschmod`, it would be `oschmod.oschmod(...)`.

Warnings

• gotcha On Windows, `oschmod` translates POSIX-like mode bits to Windows Access Control Lists (ACLs). This is an approximation and not all POSIX modes have direct ACL equivalents, which can lead to slightly different effective permissions or limitations compared to a true POSIX system.
  Fix: Be aware of potential differences in permission interpretation on Windows. For fine-grained Windows permissions, consider using a dedicated ACL management library.
• gotcha The `oschmod` function is not recursive by default. It only modifies the permissions of the specified file or directory itself. To apply permissions to the contents of a directory, you must manually traverse the directory tree (e.g., using `os.walk`).
  Fix: Implement directory traversal logic using `os.walk` or similar methods if you need to set permissions recursively for a directory's contents.
• gotcha Attempting to change permissions on files or directories where the current user lacks the necessary administrative or ownership privileges will result in a `PermissionError`. This is especially common on Windows for system files or on Linux for files owned by root.
  Fix: Ensure the script is run with appropriate user privileges (e.g., administrator on Windows, root or sudo on Linux) or verify the current user has ownership/write permissions for the target file/directory.

Install

• pip install oschmod Install oschmod

Imports

• oschmod
  wrong:

  import oschmod; oschmod.chmod('file', 0o755)

  correct:

  from oschmod import oschmod

  The main function for changing permissions is also named 'oschmod' within the 'oschmod' module.

Quickstart

This quickstart demonstrates how to use the `oschmod` function to set file permissions. It creates a temporary file, sets its permissions to 0o755 (read, write, execute for owner; read, execute for group and others), and then verifies the change. Remember to use an octal literal (e.g., `0o755`) for the mode.

import os
from oschmod import oschmod

# Create a dummy file for demonstration
file_path = 'my_test_file.txt'
with open(file_path, 'w') as f:
    f.write('Hello, oschmod!')

print(f"Initial permissions for {file_path}: {oct(os.stat(file_path).st_mode & 0o777)}")

# Set permissions to rwxr-xr-x (0o755)
oschmod(file_path, 0o755)

print(f"New permissions for {file_path}: {oct(os.stat(file_path).st_mode & 0o777)}")

# Clean up the dummy file
os.remove(file_path)