Usage Guide¶

Basic Usage¶

The bad_path package provides several functions for checking if a file path points to a system-sensitive location. It also provides a PathChecker class for a more object-oriented approach with additional details.

Checking for Dangerous Paths¶

The simplest way to check if a path is dangerous:

from bad_path import is_dangerous_path

# Returns True if the path is dangerous, False otherwise
if is_dangerous_path("/etc/passwd"):
    print("This is a dangerous path!")

Using the PathChecker Class¶

The PathChecker class provides a more detailed interface that distinguishes between platform-specific system paths and user-defined sensitive paths:

from bad_path import PathChecker

# Create a checker for a path
checker = PathChecker("/etc/passwd")

# Use it in boolean context
if not checker:
    print("This is a dangerous path!")
    print(f"Is system path: {checker.is_system_path}")
    print(f"Is user-defined sensitive: {checker.is_sensitive_path}")

# Access the original path
print(f"Checked path: {checker.path}")

The PathChecker class evaluates to True when used in boolean context if the path is safe (not a system path or user-defined dangerous path), and False if the path is dangerous. The is_system_path property checks against platform-specific dangerous paths (like /etc, /bin on Linux, or C:\\Windows on Windows), while is_sensitive_path checks against user-defined paths added via add_user_path().

Checking Path Accessibility¶

The PathChecker class also provides properties to check if a path is accessible for read, write, or create operations:

from bad_path import PathChecker

checker = PathChecker("/etc/passwd")

# Check if path is readable
if checker.is_readable:
    print("Path can be read")

# Check if path is writable
if checker.is_writable:
    print("Path can be written to")

# Check if a non-existent path can be created
checker2 = PathChecker("/tmp/new_file.txt")
if checker2.is_creatable:
    print("Path can be created")

The accessibility properties work as follows:

is_readable: Returns True if the path exists and has read permission
is_writable: Returns True if the path exists and has write permission
is_creatable: Returns True if the path doesn’t exist but can be created (parent directory is writable)

These properties are useful for checking whether your application has the necessary permissions to perform operations on a path, in addition to checking if the path is in a dangerous location.

Raising Exceptions¶

You can also have the function raise an exception instead of returning a boolean:

from bad_path import is_dangerous_path, DangerousPathError

try:
    is_dangerous_path("/etc/passwd", raise_error=True)
except DangerousPathError as e:
    print(f"Error: {e}")

Using Path Objects¶

The package works with both strings and pathlib.Path objects:

from pathlib import Path
from bad_path import is_dangerous_path

path = Path("/etc/passwd")
if is_dangerous_path(path):
    print("Dangerous!")

Getting Dangerous Paths for Current OS¶

To see which paths are considered dangerous on the current platform:

from bad_path import get_dangerous_paths

dangerous = get_dangerous_paths()
for path in dangerous:
    print(f"Dangerous path: {path}")

Platform-Specific Behavior¶

The package automatically detects the current operating system and uses appropriate dangerous path lists:

Windows: System directories like C:\\Windows, C:\\Program Files
macOS: System directories like /System, /Library
Linux: System directories like /etc, /bin, /usr

Examples¶

Using PathChecker for Detailed Feedback¶

from bad_path import PathChecker

def validate_path(path):
    """Validate a path and provide detailed feedback."""
    checker = PathChecker(path)

    if not checker:
        reasons = []
        if checker.is_system_path:
            reasons.append("it's a platform-specific system path")
        if checker.is_sensitive_path:
            reasons.append("it's a user-defined sensitive location")
        print(f"❌ Cannot use {path} because {' and '.join(reasons)}")
        return False

    print(f"✅ Path {path} is safe to use")
    return True

Validating User Input¶

from bad_path import is_dangerous_path, DangerousPathError

def save_file(filepath, content):
    """Save content to a file, but only if it's not in a dangerous location."""
    try:
        is_dangerous_path(filepath, raise_error=True)
    except DangerousPathError:
        raise ValueError("Cannot write to system directories!")

    with open(filepath, 'w') as f:
        f.write(content)

Filtering File Lists¶

from bad_path import is_system_path
import os

def get_safe_files(directory):
    """Get all files in a directory that are not in system locations."""
    safe_files = []
    for root, dirs, files in os.walk(directory):
        for file in files:
            filepath = os.path.join(root, file)
            if not is_system_path(filepath):
                safe_files.append(filepath)
    return safe_files

Combining Danger and Accessibility Checks¶

from bad_path import PathChecker

def safe_to_write(filepath):
    """Check if a path is both safe (not dangerous) and writable."""
    checker = PathChecker(filepath)

    # PathChecker evaluates to True for safe paths
    if not checker:
        print(f"❌ {filepath} is in a dangerous location!")
        return False

    # Path must be writable or creatable
    if not (checker.is_writable or checker.is_creatable):
        print(f"❌ {filepath} is not accessible for writing!")
        return False

    print(f"✅ {filepath} is safe and writable")
    return True

# Usage
safe_to_write("/tmp/myfile.txt")      # ✅ Safe and creatable
safe_to_write("/etc/passwd")          # ❌ Dangerous location
safe_to_write("/root/restricted.txt") # ❌ Not accessible (if not root)

bad_path 0.2.1 documentation