pafex 2.3__tar.gz

pafex-2.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 pafex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pafex-2.3/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: pafex
+Version: 2.3
+Summary: Minimal checksummed binary configuration handling.
+Author-email: redomaitic <redomaitic@gmail.com>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+Minimal checksummed binary configuration handling for Python. `Config`
+layers user settings over `DEFAULT_CONFIG`; `load_config`/`save_config`
+persist to a strict binary format with optional gzip/xz/zlib compression.
+Standard library only.
+
+## Install
+
+```bash
+pip install pafex
+```
+
+## Usage
+
+```python
+from pafex import Config, load_config, save_config
+
+cfg = Config({'strict_mode': True, 'allowed_tags': {'p', 'a'}})
+cfg.get('strict_mode')                    # True
+cfg.get('strip_whitespace')               # default from DEFAULT_CONFIG
+cfg.update({'max_depth': 3})              # new Config, original untouched
+
+save_config(cfg, 'default.config', compression='gzip')
+loaded = load_config('default.config')
+loaded == cfg                             # True
+```
+
+Config file layout:
+
+```
+raw:   [8-byte MD5 checksum][4-byte size][config]
+gzip:  [8-byte MD5 checksum][4-byte size][gzip.compress(config)]
+xz:    [8-byte MD5 checksum][4-byte size][lzma.compress(config)]
+zlib:  [8-byte MD5 checksum][4-byte size][zlib.compress(config)]
+```
+
+Writes are atomic (temp file + `os.replace`). With no explicit
+path, `load_config`/`save_config` locate the caller's `default.config`
+(caller's module directory first, then the package directory).
+
+Errors raise `PafexError` subclasses: `ConfigLoadError` (read/parse
+failures), `ConfigChecksumError` (integrity mismatch) and
+`ConfigDecompressError` (corrupt compressed payload).

pafex-2.3/README.md

@@ -0,0 +1,42 @@
+Minimal checksummed binary configuration handling for Python. `Config`
+layers user settings over `DEFAULT_CONFIG`; `load_config`/`save_config`
+persist to a strict binary format with optional gzip/xz/zlib compression.
+Standard library only.
+
+## Install
+
+```bash
+pip install pafex
+```
+
+## Usage
+
+```python
+from pafex import Config, load_config, save_config
+
+cfg = Config({'strict_mode': True, 'allowed_tags': {'p', 'a'}})
+cfg.get('strict_mode')                    # True
+cfg.get('strip_whitespace')               # default from DEFAULT_CONFIG
+cfg.update({'max_depth': 3})              # new Config, original untouched
+
+save_config(cfg, 'default.config', compression='gzip')
+loaded = load_config('default.config')
+loaded == cfg                             # True
+```
+
+Config file layout:
+
+```
+raw:   [8-byte MD5 checksum][4-byte size][config]
+gzip:  [8-byte MD5 checksum][4-byte size][gzip.compress(config)]
+xz:    [8-byte MD5 checksum][4-byte size][lzma.compress(config)]
+zlib:  [8-byte MD5 checksum][4-byte size][zlib.compress(config)]
+```
+
+Writes are atomic (temp file + `os.replace`). With no explicit
+path, `load_config`/`save_config` locate the caller's `default.config`
+(caller's module directory first, then the package directory).
+
+Errors raise `PafexError` subclasses: `ConfigLoadError` (read/parse
+failures), `ConfigChecksumError` (integrity mismatch) and
+`ConfigDecompressError` (corrupt compressed payload).

pafex-2.3/pafex/__init__.py

@@ -0,0 +1,29 @@
+"""pafex: minimal checksummed binary configuration handling."""
+
+from .exceptions import (
+    ConfigChecksumError,
+    ConfigDecompressError,
+    ConfigLoadError,
+    PafexError,
+)
+from .config import (
+    CONFIG_NAME,
+    DEFAULT_CONFIG,
+    Config,
+    find_default_config,
+    load_config,
+    save_config,
+)
+
+__all__ = [
+    'Config',
+    'DEFAULT_CONFIG',
+    'CONFIG_NAME',
+    'load_config',
+    'save_config',
+    'find_default_config',
+    'PafexError',
+    'ConfigLoadError',
+    'ConfigChecksumError',
+    'ConfigDecompressError',
+]

pafex-2.3/pafex/config.py

@@ -0,0 +1,255 @@
+"""Configuration loading and persistence for the pafex package.
+
+Config files use a strict binary layout:
+
+    raw:   [8-byte MD5 checksum][4-byte size][payload]
+    gzip:  [8-byte MD5 checksum][4-byte size][gzip.compress(payload)]
+    xz:    [8-byte MD5 checksum][4-byte size][lzma.compress(payload)]
+    zlib:  [8-byte MD5 checksum][4-byte size][zlib.compress(payload)]
+"""
+
+import gzip
+import hashlib
+import importlib.util
+import lzma
+import os
+import pickle
+import sys
+import tempfile
+import types
+import zlib
+from pathlib import Path
+from typing import Any, Dict, Mapping, Optional, Tuple, Union
+
+from .exceptions import ConfigChecksumError, ConfigDecompressError, ConfigLoadError
+
+PathLike = Union[str, os.PathLike]
+
+DEFAULT_CONFIG: Mapping[str, Any] = types.MappingProxyType({
+    'parse_tables': True,
+    'strip_whitespace': True,
+    'encoding': 'utf-8',
+    'max_depth': 100,
+    'default_tag': 'div',
+    'preserve_comments': False,
+    'strict_mode': False,
+    'remove_comments': True,
+    'allowed_tags': frozenset({'p', 'br', 'b', 'i', 'a', 'ul', 'ol', 'li', 'div', 'span'}),
+    'max_file_size_mb': 10,
+    'cache_size': 50,
+})
+
+_CHECKSUM_SIZE = 8
+_SIZE_SIZE = 4
+_HEADER_SIZE = _CHECKSUM_SIZE + _SIZE_SIZE
+
+
+def _checksum(payload: bytes) -> bytes:
+    """First _CHECKSUM_SIZE bytes of the MD5 digest of payload."""
+    return hashlib.md5(payload).digest()[:_CHECKSUM_SIZE]
+
+
+def _detect_compression(data: bytes) -> Optional[Tuple[str, Any]]:
+    """Detect compression format by magic bytes. Returns (name, module) or None.
+
+    zlib has no magic number; it is detected last by validating its CMF/FLG
+    header (deflate method, CINFO <= 7, no preset dictionary, header value
+    divisible by 31).
+    """
+    if data[:2] == b'\x1f\x8b':
+        return 'gzip', gzip
+    if data[:6] == b'\xfd7zXZ\x00':
+        return 'xz', lzma
+    if (
+        len(data) >= 2
+        and data[0] & 0x0F == 8
+        and data[0] >> 4 <= 7
+        and not data[1] & 0x20
+        and ((data[0] << 8) | data[1]) % 31 == 0
+    ):
+        return 'zlib', zlib
+    return None
+
+
+def _verify_header(data: bytes, path: PathLike) -> bytes:
+    """Verify the 8-byte MD5 and 4-byte size header; return the payload."""
+    if len(data) < _HEADER_SIZE:
+        raise ConfigLoadError(
+            f"config file '{path}' is too short to be a valid config file"
+        )
+    stored = data[:_CHECKSUM_SIZE]
+    size = int.from_bytes(data[_CHECKSUM_SIZE:_HEADER_SIZE], 'big')
+    payload = data[_HEADER_SIZE:]
+    if len(payload) != size:
+        raise ConfigLoadError(
+            f"size mismatch in config file '{path}': file truncated or "
+            f"tampered with; expected {size} payload bytes, got {len(payload)}"
+        )
+    if _checksum(payload) != stored:
+        raise ConfigChecksumError(
+            f"checksum mismatch in config file '{path}': file may be corrupted "
+            "or tampered with; files written by older versions are not accepted"
+        )
+    return payload
+
+
+def _sanitize_value(value: Any) -> Any:
+    """Recursively verify that a value only contains allowed plain types."""
+    if isinstance(value, (str, bytes, int, float, bool, type(None))):
+        return value
+    if isinstance(value, dict):
+        return {str(key): _sanitize_value(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_sanitize_value(item) for item in value]
+    if isinstance(value, (set, frozenset)):
+        return {_sanitize_value(item) for item in value}
+    raise ConfigLoadError(
+        f'disallowed type {type(value).__name__!r} in config file; '
+        'only plain data types are allowed'
+    )
+
+
+class Config:
+    """Configuration holder that layers user settings over DEFAULT_CONFIG."""
+
+    def __init__(self, settings: Optional[Dict[str, Any]] = None):
+        self._settings: Dict[str, Any] = {**DEFAULT_CONFIG, **(settings or {})}
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self._settings.get(key, default)
+
+    def update(self, settings: Dict[str, Any]) -> 'Config':
+        """Return a new Config with extra settings layered on top of this one."""
+        return Config({**self._settings, **(settings or {})})
+
+    def to_dict(self) -> Dict[str, Any]:
+        return dict(self._settings)
+
+    @classmethod
+    def load_default(cls) -> 'Config':
+        """Return a Config built from DEFAULT_CONFIG without reading any file."""
+        return cls()
+
+    def __eq__(self, other: Any) -> bool:
+        if isinstance(other, Config):
+            return self._settings == other._settings
+        return NotImplemented
+
+    def __repr__(self) -> str:
+        return f'Config({self._settings})'
+
+
+def _read_config(path: PathLike) -> Dict[str, Any]:
+    """Read config bytes from path."""
+    try:
+        with open(path, 'rb') as handle:
+            data = handle.read()
+    except Exception as exc:
+        raise ConfigLoadError(f"failed to read config file '{path}': {exc}") from exc
+
+    blob = _verify_header(data, path)
+
+    detected = _detect_compression(blob)
+    if detected is not None:
+        name, module = detected
+        try:
+            blob = module.decompress(blob)
+        except Exception as exc:
+            raise ConfigDecompressError(
+                f"failed to decompress {name} config file '{path}': {exc}"
+            ) from exc
+
+    try:
+        loaded = pickle.loads(blob)
+    except Exception as exc:
+        raise ConfigLoadError(
+            f"failed to load pickle payload from '{path}': {exc}"
+        ) from exc
+    if not isinstance(loaded, dict):
+        raise ConfigLoadError(
+            f"config file '{path}' must contain a dict, "
+            f"got {type(loaded).__name__}"
+        )
+    return _sanitize_value(loaded)
+
+
+def load_config(path: Optional[PathLike] = None) -> Config:
+    """Load a Config from an explicit file, or the caller's default.config."""
+    if path is None:
+        path = _locate_config(sys._getframe(1).f_globals)
+    return Config(_read_config(path))
+
+
+def save_config(
+    config: Union[Config, Dict[str, Any]],
+    path: Optional[PathLike] = None,
+    compression: Optional[str] = None,
+) -> Path:
+    """Persist settings to path atomically; no path auto-finds default.config."""
+    if compression not in (None, 'gzip', 'xz', 'zlib'):
+        raise ValueError(
+            f"unsupported compression {compression!r}; expected 'gzip', 'xz', 'zlib' or None"
+        )
+
+    if path is None:
+        path = _locate_config(sys._getframe(1).f_globals)
+
+    if isinstance(config, Config):
+        settings = config.to_dict()
+    else:
+        settings = Config(config).to_dict()
+    payload = pickle.dumps(settings, protocol=pickle.HIGHEST_PROTOCOL)
+    if compression == 'gzip':
+        payload = gzip.compress(payload)
+    elif compression == 'xz':
+        payload = lzma.compress(payload)
+    elif compression == 'zlib':
+        payload = zlib.compress(payload)
+    blob = _checksum(payload) + len(payload).to_bytes(_SIZE_SIZE, 'big') + payload
+
+    target = Path(path)
+    if not target.parent.exists():
+        target.parent.mkdir(parents=True, exist_ok=True)
+
+    fd, tmp_name = tempfile.mkstemp(dir=str(target.parent), suffix='.config.tmp')
+    try:
+        with os.fdopen(fd, 'wb') as handle:
+            handle.write(blob)
+        os.replace(tmp_name, str(target))
+    except Exception:
+        try:
+            os.unlink(tmp_name)
+        except OSError:
+            pass
+        raise
+    return target
+
+
+CONFIG_NAME = 'default.config'
+
+
+def _locate_config(g: Dict[str, Any]) -> Path:
+    """Resolve the default.config path for a module globals mapping."""
+    file = g.get('__file__')
+    if file:
+        candidate = Path(os.path.abspath(file)).parent / CONFIG_NAME
+        if candidate.exists():
+            return candidate
+    package = g.get('__package__') or g.get('__name__', '').partition('.')[0]
+    if package:
+        try:
+            spec = importlib.util.find_spec(package)
+        except (ImportError, AttributeError, ValueError):
+            spec = None
+        if spec and spec.submodule_search_locations:
+            return Path(spec.submodule_search_locations[0]) / CONFIG_NAME
+    raise ConfigLoadError(f'no {CONFIG_NAME} found for caller')
+
+
+def find_default_config() -> Path:
+    """Locate the caller's default.config without loading it.
+
+    Searches the caller's module directory first, then the caller's
+    package directory. Raises ConfigLoadError when neither can be resolved.
+    """
+    return _locate_config(sys._getframe(1).f_globals)

pafex-2.3/pafex/exceptions.py

@@ -0,0 +1,17 @@
+"""Custom exceptions for pafex configuration."""
+
+
+class PafexError(Exception):
+    """Base exception for all pafex errors."""
+
+
+class ConfigLoadError(PafexError):
+    """Raised when configuration cannot be loaded."""
+
+
+class ConfigChecksumError(ConfigLoadError):
+    """Raised when a config file's checksum header does not match its payload."""
+
+
+class ConfigDecompressError(ConfigLoadError):
+    """Raised when a compressed config file cannot be decompressed."""

pafex-2.3/pafex.egg-info/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: pafex
+Version: 2.3
+Summary: Minimal checksummed binary configuration handling.
+Author-email: redomaitic <redomaitic@gmail.com>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+Minimal checksummed binary configuration handling for Python. `Config`
+layers user settings over `DEFAULT_CONFIG`; `load_config`/`save_config`
+persist to a strict binary format with optional gzip/xz/zlib compression.
+Standard library only.
+
+## Install
+
+```bash
+pip install pafex
+```
+
+## Usage
+
+```python
+from pafex import Config, load_config, save_config
+
+cfg = Config({'strict_mode': True, 'allowed_tags': {'p', 'a'}})
+cfg.get('strict_mode')                    # True
+cfg.get('strip_whitespace')               # default from DEFAULT_CONFIG
+cfg.update({'max_depth': 3})              # new Config, original untouched
+
+save_config(cfg, 'default.config', compression='gzip')
+loaded = load_config('default.config')
+loaded == cfg                             # True
+```
+
+Config file layout:
+
+```
+raw:   [8-byte MD5 checksum][4-byte size][config]
+gzip:  [8-byte MD5 checksum][4-byte size][gzip.compress(config)]
+xz:    [8-byte MD5 checksum][4-byte size][lzma.compress(config)]
+zlib:  [8-byte MD5 checksum][4-byte size][zlib.compress(config)]
+```
+
+Writes are atomic (temp file + `os.replace`). With no explicit
+path, `load_config`/`save_config` locate the caller's `default.config`
+(caller's module directory first, then the package directory).
+
+Errors raise `PafexError` subclasses: `ConfigLoadError` (read/parse
+failures), `ConfigChecksumError` (integrity mismatch) and
+`ConfigDecompressError` (corrupt compressed payload).

pafex-2.3/pafex.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+pafex/__init__.py
+pafex/config.py
+pafex/exceptions.py
+pafex.egg-info/PKG-INFO
+pafex.egg-info/SOURCES.txt
+pafex.egg-info/dependency_links.txt
+pafex.egg-info/top_level.txt

pafex-2.3/pafex.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pafex-2.3/pafex.egg-info/top_level.txt

@@ -0,0 +1 @@
+pafex

pafex-2.3/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=61.1.1", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pafex"
+version = "2.3"
+description = "Minimal checksummed binary configuration handling."
+readme = "README.md"
+license = "MIT"
+authors = [
+    {name = "redomaitic", email = "redomaitic@gmail.com"}
+]
+requires-python = ">=3.8"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+]
+
+[tool.setuptools]
+packages = ["pafex"]

pafex-2.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+