tessl/pypi-fs

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

—

Pending

Overview

Eval results

Files

Core Operations

Name: tessl/pypi-fs
Author: tessl

Essential filesystem operations that form the foundation of the FS interface. These operations are available across all filesystem implementations and provide the basic functionality needed for file and directory manipulation.

Capabilities

File Operations

Open, create, read, and write files with support for text and binary modes.

def open(self, path: str, mode: str = 'r', buffering: int = -1, encoding: str = None, errors: str = None, newline: str = None, **kwargs) -> IO:
    """
    Open a file for reading or writing.

    Parameters:
    - path: str, path to file
    - mode: str, file mode ('r', 'w', 'a', 'x', 'b', 't', '+')
    - buffering: int, buffer size (-1 for default)
    - encoding: str, text encoding (for text mode)
    - errors: str, error handling ('strict', 'ignore', 'replace')
    - newline: str, newline handling

    Returns:
    IO: File-like object

    Raises:
    - ResourceNotFound: If file doesn't exist (read mode)
    - FileExpected: If path is a directory
    - PermissionDenied: If insufficient permissions
    """

def create(self, path: str, wipe: bool = False) -> IO:
    """
    Create a new file and return file object.

    Parameters:
    - path: str, path to file
    - wipe: bool, overwrite if file exists

    Returns:
    IO: File object opened in binary write mode

    Raises:
    - FileExists: If file exists and wipe=False
    - DirectoryExpected: If parent directory doesn't exist
    """

def readtext(self, path: str, encoding: str = 'utf-8', errors: str = 'strict', newline: str = '') -> str:
    """
    Read text from a file.

    Parameters:
    - path: str, path to file
    - encoding: str, text encoding
    - errors: str, error handling
    - newline: str, newline handling

    Returns:
    str: File contents as text
    """

def writetext(self, path: str, contents: str, encoding: str = 'utf-8', errors: str = 'strict', newline: str = '') -> None:
    """
    Write text to a file.

    Parameters:
    - path: str, path to file
    - contents: str, text to write
    - encoding: str, text encoding
    - errors: str, error handling
    - newline: str, newline handling
    """

def readbytes(self, path: str) -> bytes:
    """
    Read bytes from a file.

    Parameters:
    - path: str, path to file

    Returns:
    bytes: File contents as bytes
    """

def writebytes(self, path: str, contents: bytes) -> None:
    """
    Write bytes to a file.

    Parameters:
    - path: str, path to file
    - contents: bytes, data to write
    """

Directory Operations

Create, list, and remove directories with support for nested directory structures.

def makedir(self, path: str, permissions: Permissions = None, recreate: bool = False) -> SubFS[FS]:
    """
    Create a directory.

    Parameters:
    - path: str, path to directory
    - permissions: Permissions, directory permissions
    - recreate: bool, don't raise error if directory exists

    Returns:
    SubFS[FS]: Filesystem representing the new directory

    Raises:
    - DirectoryExists: If directory exists and recreate=False
    - ResourceExists: If path exists as file
    """

def removedir(self, path: str) -> None:
    """
    Remove a directory.

    Parameters:
    - path: str, path to directory

    Raises:
    - DirectoryNotEmpty: If directory contains files
    - ResourceNotFound: If directory doesn't exist
    - DirectoryExpected: If path is a file
    """

def listdir(self, path: str = '.') -> List[str]:
    """
    List directory contents.

    Parameters:
    - path: str, path to directory

    Returns:
    List[str]: List of filenames and directory names

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

def scandir(self, path: str = '.', namespaces: List[str] = None, page: Tuple[int, int] = None) -> Iterator[Info]:
    """
    Scan directory and return Info objects.

    Parameters:
    - path: str, path to directory
    - namespaces: List[str], info namespaces to retrieve
    - page: Tuple[int, int], pagination (start, end)

    Returns:
    Iterator[Info]: Info objects for directory contents
    """

Path Queries

Query filesystem paths to determine existence, type, and properties.

def exists(self, path: str) -> bool:
    """
    Check if path exists.

    Parameters:
    - path: str, path to check

    Returns:
    bool: True if path exists
    """

def isfile(self, path: str) -> bool:
    """
    Check if path is a file.

    Parameters:
    - path: str, path to check

    Returns:
    bool: True if path is a file
    """

def isdir(self, path: str) -> bool:
    """
    Check if path is a directory.

    Parameters:
    - path: str, path to check

    Returns:
    bool: True if path is a directory
    """

def gettype(self, path: str) -> ResourceType:
    """
    Get resource type.

    Parameters:
    - path: str, path to check

    Returns:
    ResourceType: Type of resource (file, directory, etc.)
    """

def getsize(self, path: str) -> int:
    """
    Get file size in bytes.

    Parameters:
    - path: str, path to file

    Returns:
    int: File size in bytes

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

File and Directory Removal

Remove files and directories from the filesystem.

def remove(self, path: str) -> None:
    """
    Remove a file.

    Parameters:
    - path: str, path to file

    Raises:
    - ResourceNotFound: If file doesn't exist
    - FileExpected: If path is a directory
    """

def move(self, src_path: str, dst_path: str, overwrite: bool = False) -> None:
    """
    Move a file or directory.

    Parameters:
    - src_path: str, source path
    - dst_path: str, destination path
    - overwrite: bool, overwrite destination if exists

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

def copy(self, src_path: str, dst_path: str, overwrite: bool = False) -> None:
    """
    Copy a file.

    Parameters:
    - src_path: str, source file path
    - dst_path: str, destination file path
    - overwrite: bool, overwrite destination if exists

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

Metadata Operations

Access and modify file and directory metadata including timestamps, permissions, and custom attributes.

def getinfo(self, path: str, namespaces: List[str] = None) -> Info:
    """
    Get information about a resource.

    Parameters:
    - path: str, path to resource
    - namespaces: List[str], info namespaces to retrieve

    Returns:
    Info: Resource information object

    Raises:
    - ResourceNotFound: If resource doesn't exist
    """

def setinfo(self, path: str, info: RawInfo) -> None:
    """
    Set information on a resource.

    Parameters:
    - path: str, path to resource
    - info: RawInfo, information to set

    Raises:
    - ResourceNotFound: If resource doesn't exist
    """

System Operations

Operations for filesystem lifecycle management and system-level functionality.

def close(self) -> None:
    """Close the filesystem and release resources."""

def isclosed(self) -> bool:
    """
    Check if filesystem is closed.

    Returns:
    bool: True if filesystem is closed
    """

def getsyspath(self, path: str) -> str:
    """
    Get system path for a filesystem path.

    Parameters:
    - path: str, filesystem path

    Returns:
    str: System path

    Raises:
    - NoSysPath: If no system path available
    """

def geturl(self, path: str, purpose: str = 'download') -> str:
    """
    Get URL for a filesystem path.

    Parameters:
    - path: str, filesystem path
    - purpose: str, URL purpose ('download', 'upload', etc.)

    Returns:
    str: URL for the resource

    Raises:
    - NoURL: If no URL available
    """

Types

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

class SubFS:
    """Filesystem representing a subdirectory."""
    pass

class Info:
    """Resource information container."""
    pass

RawInfo = Dict[str, Dict[str, Any]]  # Raw info dictionary

class ResourceType(IntEnum):
    unknown = 0
    directory = 1
    file = 2
    character = 3
    block_special_file = 4
    fifo = 5
    socket = 6
    symlink = 7

class Permissions:
    """Unix-style permissions."""
    pass

Install with Tessl CLI