tessl/pypi-fs

Python's filesystem abstraction layer providing a unified interface for working with different types of filesystems

—

Pending

Overview

Eval results

Files

File Operations

Name: tessl/pypi-fs
Author: tessl

Advanced file and directory operations including copying, moving, walking directory trees, and pattern matching. These operations work across different filesystem types and provide high-level functionality for complex file management tasks.

Capabilities

File Copying

Copy files and directories between filesystems with support for metadata preservation and conditional copying.

def copy_file(src_fs: FS, src_path: str, dst_fs: FS, dst_path: str, overwrite: bool = False, 
              preserve_time: bool = False) -> None:
    """
    Copy file between filesystems.

    Parameters:
    - src_fs: FS, source filesystem
    - src_path: str, source file path
    - dst_fs: FS, destination filesystem 
    - dst_path: str, destination file path
    - overwrite: bool, overwrite destination if exists
    - preserve_time: bool, preserve modification time

    Raises:
    - ResourceNotFound: If source file doesn't exist
    - ResourceExists: If destination exists and overwrite=False
    - DestinationExists: If destination exists and overwrite=False
    """

def copy_file_if(src_fs: FS, src_path: str, dst_fs: FS, dst_path: str, condition: str = 'newer') -> bool:
    """
    Conditionally copy file based on condition.

    Parameters:
    - src_fs: FS, source filesystem
    - src_path: str, source file path
    - dst_fs: FS, destination filesystem
    - dst_path: str, destination file path
    - condition: str, copy condition ('newer', 'older', 'exists', 'not_exists')

    Returns:
    bool: True if file was copied

    Raises:
    - ResourceNotFound: If source file doesn't exist
    """

def copy_dir(src_fs: FS, src_path: str, dst_fs: FS, dst_path: str, 
             walker: Walker = None, on_copy: Callable = None) -> None:
    """
    Copy directory recursively between filesystems.

    Parameters:
    - src_fs: FS, source filesystem
    - src_path: str, source directory path
    - dst_fs: FS, destination filesystem
    - dst_path: str, destination directory path
    - walker: Walker, custom walker for filtering files
    - on_copy: Callable, callback function called for each copied file

    Raises:
    - ResourceNotFound: If source directory doesn't exist
    - DirectoryExpected: If source is not a directory
    """

def copy_structure(src_fs: FS, src_path: str, dst_fs: FS, dst_path: str, 
                   walker: Walker = None) -> None:
    """
    Copy directory structure without files.

    Parameters:
    - src_fs: FS, source filesystem
    - src_path: str, source directory path
    - dst_fs: FS, destination filesystem
    - dst_path: str, destination directory path
    - walker: Walker, custom walker for filtering directories

    Raises:
    - ResourceNotFound: If source directory doesn't exist
    """

def copy_modified_time(src_fs: FS, src_path: str, dst_fs: FS, dst_path: str) -> None:
    """
    Copy modification time from source to destination.

    Parameters:
    - src_fs: FS, source filesystem
    - src_path: str, source file path
    - dst_fs: FS, destination filesystem
    - dst_path: str, destination file path
    """

File Moving

Move files and directories between filesystems with atomic operations where possible.

def move_file(src_fs: FS, src_path: str, dst_fs: FS, dst_path: str, overwrite: bool = False) -> None:
    """
    Move file between filesystems.

    Parameters:
    - src_fs: FS, source filesystem
    - src_path: str, source file path
    - dst_fs: FS, destination filesystem
    - dst_path: str, destination file path
    - overwrite: bool, overwrite destination if exists

    Raises:
    - ResourceNotFound: If source file doesn't exist
    - ResourceExists: If destination exists and overwrite=False
    - CrossDeviceError: If atomic move not possible across filesystems
    """

def move_dir(src_fs: FS, src_path: str, dst_fs: FS, dst_path: str) -> None:
    """
    Move directory recursively between filesystems.

    Parameters:
    - src_fs: FS, source filesystem
    - src_path: str, source directory path
    - dst_fs: FS, destination filesystem
    - dst_path: str, destination directory path

    Raises:
    - ResourceNotFound: If source directory doesn't exist
    - DirectoryExpected: If source is not a directory
    - ResourceExists: If destination already exists
    """

Directory Walking

Traverse directory trees with filtering and callback support.

class Walker:
    """Directory tree walker with filtering capabilities."""
    
    def __init__(self, filter: List[str] = None, exclude: List[str] = None, 
                 filter_dirs: List[str] = None, exclude_dirs: List[str] = None,
                 ignore_errors: bool = False, on_error: Callable = None,
                 search: str = 'breadth', max_depth: int = None) -> None:
        """
        Create directory walker.

        Parameters:
        - filter: List[str], filename patterns to include
        - exclude: List[str], filename patterns to exclude
        - filter_dirs: List[str], directory patterns to include
        - exclude_dirs: List[str], directory patterns to exclude
        - ignore_errors: bool, ignore filesystem errors
        - on_error: Callable, error callback function
        - search: str, search order ('breadth', 'depth')
        - max_depth: int, maximum directory depth
        """
    
    def files(self, fs: FS, path: str = '/') -> Iterator[str]:
        """
        Walk files matching filters.

        Parameters:
        - fs: FS, filesystem to walk
        - path: str, starting directory path

        Returns:
        Iterator[str]: File paths
        """
    
    def dirs(self, fs: FS, path: str = '/') -> Iterator[str]:
        """
        Walk directories matching filters.

        Parameters:
        - fs: FS, filesystem to walk
        - path: str, starting directory path

        Returns:
        Iterator[str]: Directory paths
        """
    
    def info(self, fs: FS, path: str = '/', namespaces: List[str] = None) -> Iterator[Tuple[str, Info]]:
        """
        Walk with file info objects.

        Parameters:
        - fs: FS, filesystem to walk
        - path: str, starting directory path
        - namespaces: List[str], info namespaces to retrieve

        Returns:
        Iterator[Tuple[str, Info]]: (path, info) tuples
        """

def walk(fs: FS, path: str = '/', walker: Walker = None) -> Iterator[Tuple[str, List[str], List[str]]]:
    """
    Walk directory tree like os.walk.

    Parameters:
    - fs: FS, filesystem to walk
    - path: str, starting directory path
    - walker: Walker, custom walker instance

    Returns:
    Iterator[Tuple[str, List[str], List[str]]]: (dirpath, dirnames, filenames) tuples
    """

Pattern Matching and Globbing

Find files and directories using glob patterns and wildcards.

class Globber:
    """Pattern matching for filesystem paths."""
    
    def __init__(self, pattern: str, case_sensitive: bool = True) -> None:
        """
        Create globber for pattern.

        Parameters:
        - pattern: str, glob pattern (* and ? wildcards)
        - case_sensitive: bool, case sensitive matching
        """
    
    def match(self, path: str) -> bool:
        """
        Check if path matches pattern.

        Parameters:
        - path: str, path to check

        Returns:
        bool: True if path matches pattern
        """

class BoundGlobber:
    """Globber bound to specific filesystem."""
    
    def glob(self, pattern: str, path: str = '/') -> Iterator[str]:
        """
        Find paths matching glob pattern.

        Parameters:
        - pattern: str, glob pattern
        - path: str, starting directory

        Returns:
        Iterator[str]: Matching paths
        """
    
    def iglob(self, pattern: str, path: str = '/') -> Iterator[str]:
        """
        Find paths matching glob pattern (iterator).

        Parameters:
        - pattern: str, glob pattern  
        - path: str, starting directory

        Returns:
        Iterator[str]: Matching paths
        """

# Standalone glob functions
def glob_match(pattern: str, name: str, case_sensitive: bool = True) -> bool:
    """
    Test if name matches glob pattern.

    Parameters:
    - pattern: str, glob pattern
    - name: str, name to test
    - case_sensitive: bool, case sensitive matching

    Returns:
    bool: True if name matches pattern
    """

def imatch(pattern: str, name: str) -> bool:
    """
    Case-insensitive glob pattern matching.

    Parameters:
    - pattern: str, glob pattern
    - name: str, name to test

    Returns:
    bool: True if name matches pattern
    """

Tree Display

Generate text-based tree representations of directory structures.

def render(fs: FS, path: str = '/', encoding: str = 'unicode', 
           max_levels: int = 5, with_color: bool = False, 
           dirs_first: bool = True, file_out: IO = None) -> str:
    """
    Render filesystem tree as text.

    Parameters:
    - fs: FS, filesystem to render
    - path: str, root path for tree
    - encoding: str, output encoding ('unicode', 'ascii')
    - max_levels: int, maximum directory levels to show
    - with_color: bool, use ANSI color codes
    - dirs_first: bool, show directories before files
    - file_out: IO, output file object

    Returns:
    str: Tree representation as text

    Example output:
    /
    ├── documents/
    │   ├── file1.txt
    │   └── file2.txt
    └── photos/
        └── image.jpg
    """

Mirror Operations

Synchronize directory contents between filesystems.

def mirror(src_fs: FS, dst_fs: FS, walker: Walker = None, 
           preserve_time: bool = False) -> None:
    """
    Mirror source filesystem to destination.

    Parameters:
    - src_fs: FS, source filesystem
    - dst_fs: FS, destination filesystem
    - walker: Walker, custom walker for filtering
    - preserve_time: bool, preserve modification times

    Note:
    This operation makes dst_fs identical to src_fs by copying missing files,
    updating changed files, and removing extra files from destination.
    """

Usage Examples

Copying files between different filesystem types:

from fs import open_fs
from fs.copy import copy_file, copy_dir

# Copy file from local to ZIP archive
local_fs = open_fs('.')
zip_fs = open_fs('zip://backup.zip', writeable=True)

copy_file(local_fs, 'document.txt', zip_fs, 'backup/document.txt')

# Copy entire directory to memory filesystem
from fs.memoryfs import MemoryFS
mem_fs = MemoryFS()
copy_dir(local_fs, 'photos', mem_fs, 'backup_photos')

Walking directory trees with filtering:

from fs import open_fs
from fs.walk import Walker

fs = open_fs('.')

# Find all Python files
walker = Walker(filter=['*.py'])
for path in walker.files(fs):
    print(f"Python file: {path}")

# Find large files (using info)
walker = Walker()
for path, info in walker.info(fs, namespaces=['details']):
    if info.size > 1024 * 1024:  # > 1MB
        print(f"Large file: {path} ({info.size} bytes)")

Pattern matching:

from fs import open_fs
from fs.glob import glob_match

fs = open_fs('.')

# Check if files match patterns
print(glob_match('*.txt', 'readme.txt'))      # True
print(glob_match('test_*.py', 'test_main.py')) # True

# Use bound globber for filesystem searching
for path in fs.glob('**/*.py'):
    print(f"Python file: {path}")

Displaying directory trees:

from fs import open_fs
from fs.tree import render

fs = open_fs('.')
tree_text = render(fs, max_levels=3, with_color=True)
print(tree_text)

Types

from typing import Iterator, List, Tuple, Callable, IO, Optional, Union

class Info:
    """File information object."""
    pass

WalkCallback = Callable[[str], None]
ErrorCallback = Callable[[Exception], None]

Install with Tessl CLI