tessl/pypi-fs

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

—

Pending

Overview

Eval results

Files

Filesystem Management

Name: tessl/pypi-fs
Author: tessl

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

Capabilities

Opening Filesystems

Open filesystems using URL-style strings that specify the filesystem type and location.

def open_fs(fs_url: str, writeable: bool = False, create: bool = False, cwd: str = ".", default_protocol: str = "osfs") -> FS:
    """
    Open a filesystem from a URL.

    Parameters:
    - fs_url: str, filesystem URL (e.g., '.', 'mem://', 'zip://archive.zip')
    - writeable: bool, open filesystem in writeable mode (default: False)
    - create: bool, create filesystem if it doesn't exist (default: False)
    - cwd: str, current working directory for relative paths (default: ".")
    - default_protocol: str, protocol to use if none specified (default: "osfs")

    Returns:
    FS: Filesystem instance

    Raises:
    - FSError: If filesystem cannot be opened
    - UnsupportedProtocol: If URL scheme is not supported
    """

URL Parsing

Parse filesystem URLs into their components for analysis or custom processing.

def parse(fs_url: str) -> ParsedURL:
    """
    Parse a filesystem URL into components.

    Parameters:
    - fs_url: str, filesystem URL to parse

    Returns:
    ParsedURL: Parsed URL components (protocol, path, params)
    """

Filesystem Registry

Global registry for managing filesystem openers and their associated URL schemes.

class Registry:
    def open_fs(self, fs_url: str, **kwargs) -> FS: ...
    def open(self, fs_url: str, **kwargs) -> FS: ...
    def manage_fs(self, fs_url: str, **kwargs): ...  # Context manager
    def install(self, opener: Opener) -> None: ...
    def get_opener(self, protocol: str) -> Opener: ...

URL Schemes

Common filesystem URL schemes supported by the opener system:

file:// or . - Local filesystem (OSFS)
mem:// - Memory filesystem (MemoryFS)
zip://path/to/file.zip - ZIP archive filesystem (ZipFS)
tar://path/to/file.tar - TAR archive filesystem (TarFS)
ftp://user:pass@host/path - FTP filesystem (FTPFS)
temp:// - Temporary filesystem (TempFS)
osfs://path - Operating system filesystem (OSFS)

Usage Examples

Opening different filesystem types:

from fs import open_fs

# Local directory
local_fs = open_fs('.')
home_fs = open_fs('~')

# Memory filesystem
mem_fs = open_fs('mem://')

# ZIP archive (read-only by default)
zip_fs = open_fs('zip://data.zip')

# ZIP archive (writeable)
zip_fs = open_fs('zip://data.zip', writeable=True)

# FTP server
ftp_fs = open_fs('ftp://user:pass@example.com/uploads')

# Temporary directory (auto-cleanup)
temp_fs = open_fs('temp://')

Using as context manager:

from fs.opener import manage_fs

with manage_fs('temp://') as temp_fs:
    temp_fs.writetext('hello.txt', 'Hello World!')
    # Filesystem automatically cleaned up on exit

Types

class ParsedURL:
    protocol: str
    username: str
    password: str  
    resource: str
    params: Dict[str, str]

class Opener:
    def open_fs(self, fs_url: str, parse_result: ParsedURL, writeable: bool, create: bool, cwd: str) -> FS: ...

class UnsupportedProtocol(FSError):
    """Protocol not supported by any opener."""
    pass

class ParseError(FSError):
    """Failed to parse filesystem URL."""
    pass

registry: Registry  # Global registry instance

Install with Tessl CLI