PyFileSystem2 (fs)

Python's filesystem abstraction layer providing a unified interface for working with different types of filesystems including local directories, ZIP archives, FTP servers, memory filesystems, and more. PyFileSystem2 enables developers to write filesystem code once and have it work seamlessly across various storage backends without modification.

Package Information

• Package Name: fs
• Language: Python
• Installation: pip install fs

Core Imports

import fs
from fs import open_fs
from fs import path

For specific filesystem types:

from fs.osfs import OSFS
from fs.memoryfs import MemoryFS
from fs.zipfs import ZipFS

Basic Usage

from fs import open_fs

# Open different types of filesystems using URLs
local_fs = open_fs('.')
memory_fs = open_fs('mem://')
zip_fs = open_fs('zip://archive.zip')

# All filesystems use the same API
with local_fs.open('hello.txt', 'w') as f:
    f.write('Hello, World!')

# List directory contents
for path in local_fs.listdir('.'):
    print(path)

# Copy files between different filesystem types
local_fs.copy('hello.txt', memory_fs, 'hello_copy.txt')

# Walk directory trees
for path in local_fs.walk.files():
    print(f"File: {path}")

Architecture

PyFileSystem2 follows a layered architecture:

• FS Base Class: Abstract interface defining the common filesystem API
• Filesystem Implementations: Concrete implementations for different storage types (local, memory, archives, network)
• Opener System: URL-based filesystem creation and management
• Utility Modules: Path manipulation, copying, walking, globbing, and other filesystem operations
• Error Handling: Comprehensive exception hierarchy for robust error management

This design enables maximum portability and reusability, allowing filesystem code to work across diverse storage systems while maintaining a consistent, Pythonic API.

Capabilities

Filesystem Opening and Management

Create and manage filesystem instances using URLs or direct instantiation. The opener system provides a unified way to work with different filesystem types through URL-style strings.

def open_fs(fs_url: str, **kwargs) -> FS: ...

Filesystem Management

Core Filesystem Operations

Essential filesystem operations including file and directory manipulation, metadata access, and path operations. These operations form the foundation of the FS interface and are available across all filesystem implementations.

class FS:
    def open(self, path: str, mode: str = 'r', **kwargs) -> IO: ...
    def exists(self, path: str) -> bool: ...
    def isfile(self, path: str) -> bool: ...
    def isdir(self, path: str) -> bool: ...
    def listdir(self, path: str = '.') -> List[str]: ...
    def makedir(self, path: str, **kwargs) -> SubFS: ...
    def remove(self, path: str) -> None: ...
    def removedir(self, path: str) -> None: ...

Core Operations

Filesystem Implementations

Concrete filesystem implementations for different storage backends including local directories, memory filesystems, archives, and network filesystems.

class OSFS(FS): ...
class MemoryFS(FS): ...
class ZipFS(FS): ...
class TarFS(FS): ...
class FTPFS(FS): ...
class TempFS(FS): ...

Filesystem Types

Path Operations

Platform-agnostic path manipulation utilities that work consistently across different operating systems and filesystem types.

def join(*paths: str) -> str: ...
def split(path: str) -> Tuple[str, str]: ...
def dirname(path: str) -> str: ...
def basename(path: str) -> str: ...
def abspath(path: str) -> str: ...
def normpath(path: str) -> str: ...

Path Operations

File and Directory Operations

Advanced file and directory operations including copying, moving, walking directory trees, and pattern matching.

def copy_file(src_fs: FS, src_path: str, dst_fs: FS, dst_path: str) -> None: ...
def copy_dir(src_fs: FS, src_path: str, dst_fs: FS, dst_path: str) -> None: ...
def move_file(src_fs: FS, src_path: str, dst_fs: FS, dst_path: str) -> None: ...
def walk(fs: FS, path: str = '/') -> Iterator[Tuple[str, List[str], List[str]]]: ...

File Operations

Error Handling

Comprehensive exception hierarchy providing specific error types for different filesystem operation failures.

class FSError(Exception): ...
class ResourceNotFound(FSError): ...
class ResourceExists(FSError): ...
class DirectoryExpected(FSError): ...
class FileExpected(FSError): ...
class PermissionDenied(FSError): ...

Error Handling