#exonware/xwsystem/src/exonware/xwsystem/io/defs.py
"""
Company: eXonware.com
Author: eXonware Backend Team
Email: connect@exonware.com
Version: 0.9.0.23
Generation Date: 30-Oct-2025
IO module definitions - ALL enums and types in ONE place.
Consolidated from all submodules for maintainability.
"""

from enum import Enum, IntEnum, Flag, IntFlag, auto
from typing import Any
from dataclasses import dataclass
# From ROOT

class FileMode(Enum):
    """File operation modes."""
    READ = "r"
    WRITE = "w"
    APPEND = "a"
    READ_WRITE = "r+"
    WRITE_READ = "w+"
    APPEND_READ = "a+"
    BINARY_READ = "rb"
    BINARY_WRITE = "wb"
    BINARY_APPEND = "ab"
    BINARY_READ_WRITE = "rb+"
    BINARY_WRITE_READ = "wb+"
    BINARY_APPEND_READ = "ab+"
# From ROOT

class FileType(Enum):
    """File types."""
    TEXT = "text"
    BINARY = "binary"
    JSON = "json"
    YAML = "yaml"
    XML = "xml"
    CSV = "csv"
    CONFIG = "config"
    LOG = "log"
    TEMP = "temp"
    BACKUP = "backup"
# From ROOT

class PathType(Enum):
    """Path types."""
    FILE = "file"
    DIRECTORY = "directory"
    LINK = "link"
    UNKNOWN = "unknown"
# From ROOT  

class OperationResult(Enum):
    """Operation result status."""
    SUCCESS = "success"
    FAILURE = "failure"
    PARTIAL = "partial"
    SKIPPED = "skipped"
# From ROOT

class LockType(Enum):
    """Lock types for file operations."""
    SHARED = "shared"
    EXCLUSIVE = "exclusive"
    NONE = "none"
# From common

class AtomicMode(Enum):
    """Atomic operation modes."""
    WRITE = "write"              # Write with temp file
    WRITE_BACKUP = "write_backup"  # Write with backup
    MOVE = "move"                # Atomic move
    COPY = "copy"                # Atomic copy
# From common

class WatcherEvent(Enum):
    """File watcher event types."""
    CREATED = "created"
    MODIFIED = "modified"
    DELETED = "deleted"
    MOVED = "moved"
# From common

class LockMode(Enum):
    """File lock modes."""
    EXCLUSIVE = "exclusive"      # Exclusive lock
    SHARED = "shared"            # Shared lock
    BLOCKING = "blocking"        # Block until acquired
    NON_BLOCKING = "non_blocking"  # Return immediately
# From common

class PathSecurityLevel(Enum):
    """Path validation security levels."""
    STRICT = "strict"            # Maximum validation
    MODERATE = "moderate"        # Standard validation
    RELAXED = "relaxed"          # Minimal validation
    DISABLED = "disabled"        # No validation (unsafe!)
# From file

class PagingMode(Enum):
    """Paging strategies for file reading."""
    BYTE = "byte"                # Page by byte offsets
    LINE = "line"                # Page by line counts
    RECORD = "record"            # Page by record boundaries
    SMART = "smart"              # Adaptive paging
    AUTO = "auto"                # Auto-detect strategy
# From file

class FileEncoding(Enum):
    """Common file encodings."""
    UTF8 = "utf-8"
    UTF16 = "utf-16"
    UTF32 = "utf-32"
    ASCII = "ascii"
    LATIN1 = "latin-1"
    CP1252 = "cp1252"
# From folder

class TraversalMode(Enum):
    """Directory traversal modes."""
    DEPTH_FIRST = "depth_first"
    BREADTH_FIRST = "breadth_first"
    FILES_ONLY = "files_only"
    DIRS_ONLY = "dirs_only"
# From stream

class StreamMode(Enum):
    """Stream operation modes."""
    SYNC = "sync"
    ASYNC = "async"
# From stream

class CodecIOMode(Enum):
    """Codec I/O modes."""
    FULL = "full"        # Load entire file
    PAGED = "paged"      # Page by page
    STREAMING = "streaming"  # Stream items
# From filesystem

class FSScheme(Enum):
    """Filesystem scheme types."""
    FILE = "file"        # Local filesystem
    S3 = "s3"            # Amazon S3
    FTP = "ftp"          # FTP
    SFTP = "sftp"        # SFTP
    HTTP = "http"        # HTTP
    ZIP = "zip"          # ZIP archive as FS
    MEM = "mem"          # In-memory FS
# From archive

class ArchiveFormat(Enum):
    """
    Archive format types.
    Current: ZIP, TAR
    Future: 7Z, RAR, CAB, ISO, etc.
    """
    ZIP = "zip"
    TAR = "tar"
    TAR_GZ = "tar.gz"
    TAR_BZ2 = "tar.bz2"
    TAR_XZ = "tar.xz"
    # Future formats (extensible!)
    SEVEN_ZIP = "7z"        # 7-Zip
    RAR = "rar"             # WinRAR
    CAB = "cab"             # Cabinet
    ISO = "iso"             # ISO image
    ARJ = "arj"             # ARJ
    LZH = "lzh"             # LHA/LZH
    ACE = "ace"             # ACE
# From archive

class CompressionAlgorithm(Enum):
    """
    Compression algorithm types.
    Current: gzip, bz2, lzma
    Future: zstd, brotli, snappy, lz4, etc.
    """
    NONE = "none"
    GZIP = "gzip"
    BZ2 = "bz2"
    LZMA = "lzma"
    # Future algorithms (extensible!)
    ZSTD = "zstd"           # Zstandard (faster than gzip)
    BROTLI = "brotli"       # Brotli (Google)
    SNAPPY = "snappy"       # Snappy (fast)
    LZ4 = "lz4"             # LZ4 (very fast)
    XZ = "xz"               # XZ (high compression)
# From archive

class CompressionLevel(Enum):
    """Compression level presets."""
    FAST = 1                # Fastest compression
    BALANCED = 6            # Balance speed/size
    BEST = 9                # Maximum compression
# From manager

class ManagerMode(Enum):
    """Manager operation modes."""
    STRICT = "strict"
    RELAXED = "relaxed"
# From codec

class CodecCapability(Flag):
    """Codec capabilities for introspection."""
    STREAMING = auto()
    BIDIRECTIONAL = auto()
    SCHEMA_BASED = auto()
    BINARY_OUTPUT = auto()
    TEXT_OUTPUT = auto()
    COMPRESSION = auto()


class CodecCategory(Enum):
    """
    Codec categories for format conversion compatibility.
    Formats can only convert within the same category:
    - ARCHIVE: zip ↔ 7z ✓ (both archives)
    - SERIALIZATION: json ↔ yaml ✓ (both serialization)
    - ARCHIVE ↔ SERIALIZATION: ✗ (incompatible)
    """
    SERIALIZATION = "serialization"  # json, yaml, xml, toml, pickle
    ARCHIVE = "archive"              # zip, 7z, tar, rar, zst
    FORMATTER = "formatter"          # sql, html, markdown
    ENCRYPTION = "encryption"        # aes, rsa
    ENCODING = "encoding"            # base64, hex, url
    COMPRESSION = "compression"      # gzip, bz2, lzma (raw compression)
