or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/pypi-whichcraft

Cross-platform cross-python shutil.which functionality for finding executable programs in the system PATH.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/whichcraft@0.6.x

To install, run

npx @tessl/cli install tessl/pypi-whichcraft@0.6.0

index.mddocs/

whichcraft

whichcraft provides cross-platform cross-python shutil.which functionality for finding executable programs in the system PATH. It serves as a compatibility shim that works across multiple Python versions (2.7, 3.6, 3.7+) and operating systems (Linux, macOS, Windows), addressing the gap where shutil.which was only available in Python 3.3+.

Package Information

  • Package Name: whichcraft
  • Package Type: pypi
  • Language: Python
  • Installation: pip install whichcraft

Core Imports

from whichcraft import which

Module import:

import whichcraft
# Access as whichcraft.which()

Basic Usage

from whichcraft import which

# Find a command in PATH
executable_path = which('python')
if executable_path:
    print(f"Python found at: {executable_path}")
else:
    print("Python not found in PATH")

# Search for common utilities
date_cmd = which('date')          # '/bin/date' on Unix-like systems
git_cmd = which('git')            # Path to git executable if installed
nonexistent = which('fake-cmd')   # None if not found

# Custom search path
custom_path = which('python', path='/usr/local/bin:/usr/bin')

# Custom file access mode
executable = which('script.py', mode=os.F_OK | os.X_OK)

Capabilities

Executable Discovery

Locates executable programs in the system PATH with cross-platform compatibility and Python version independence.

def which(cmd, mode=os.F_OK | os.X_OK, path=None):
    """
    Given a command, mode, and a PATH string, return the path which
    conforms to the given mode on the PATH, or None if there is no such
    file.

    Parameters:
    - cmd (str): Command name to search for
    - mode (int, optional): File access mode, defaults to os.F_OK | os.X_OK
    - path (str, optional): Custom search path, defaults to os.environ.get("PATH")

    Returns:
    str or None: Full path to executable if found, None otherwise

    Platform-specific behavior:
    - Windows: Handles PATHEXT environment variable and current directory precedence
    - Unix-like: Direct command search without extensions
    """

Usage Examples

Basic executable search:

from whichcraft import which

# Find Python interpreter
python_path = which('python')
if python_path:
    print(f"Python executable: {python_path}")

# Find system utilities
date_path = which('date')      # Unix/Linux/macOS
where_path = which('where')    # Windows

Custom search path:

import os
from whichcraft import which

# Search in specific directories
custom_path = '/usr/local/bin:/opt/bin'
result = which('custom-tool', path=custom_path)

# Search in environment PATH plus additional directory
extended_path = os.environ.get('PATH') + os.pathsep + '/home/user/bin'
result = which('my-script', path=extended_path)

Custom file access mode:

import os
from whichcraft import which

# Default mode: readable and executable
default_result = which('python')

# Custom mode: only check if file exists
exists_result = which('python', mode=os.F_OK)

# Custom mode: readable, writable, and executable
rwx_result = which('python', mode=os.F_OK | os.R_OK | os.W_OK | os.X_OK)

Platform-Specific Behavior

Windows

  • PATHEXT handling: Automatically appends extensions (.exe, .bat, .cmd, etc.) from PATHEXT environment variable
  • Current directory precedence: Searches current directory first if not explicitly in PATH
  • Case insensitive: Command matching is case-insensitive

Unix-like Systems (Linux, macOS)

  • No extensions: Searches for exact command name without adding extensions
  • Case sensitive: Command matching is case-sensitive
  • Standard PATH search: Follows traditional Unix PATH behavior

Compatibility

  • Python 2.7: Full support with custom implementation
  • Python 3.6+: Uses shutil.which when available, falls back to custom implementation
  • Cross-platform: Windows, Linux, macOS support
  • Fallback implementation: Provides shutil.which functionality for Python < 3.3

Types

# Module-level constants
__author__: str = "Daniel Roy Greenfeld"
__email__: str = "pydanny@gmail.com"  
__version__: str = "0.6.1"

Error Handling

The which function handles errors gracefully:

  • Non-existent commands: Returns None instead of raising exceptions
  • Invalid paths: Returns None for inaccessible directories
  • Permission errors: Uses os.access() to check permissions before returning paths
  • Import fallback: Gracefully falls back to custom implementation when shutil.which is unavailable