appxc 0.0.3.dev384__py3-none-any.whl

appxc/__init__.py

@@ -0,0 +1,25 @@
+# Copyright 2023-2026 the contributors of APPXC (github.com/alexander-nbg/appxc)
+# SPDX-License-Identifier: Apache-2.0
+"""Facade for APPXC basic classes"""
+# Basic classes exposed here shall only have dependencies to python builtin
+# modules. This facade shall not expose any object from sub-modules. Rationale:
+# using APPXC shall not enforce loading of unnecessary dependencies which are
+# typically present in sub-modules.
+
+# try:
+#     from ._version import __version__ as __version__
+# except ImportError:
+#     # Package was not installed; version metadata is unknown (e.g. running directly
+#     # from source without hatch-vcs build hook execution).
+#     __version__: str = "0.0.0.dev0+unknown"
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("package-name")
+except PackageNotFoundError:
+    # package is not installed
+    __version__ = "0.0.0.dev0+unknown"
+
+from .options import Options
+from .stateful import Stateful

appxc/build/__init__.py

@@ -0,0 +1,6 @@
+# Copyright 2026 the contributors of APPXC (github.com/alexander-nbg/appxc)
+# SPDX-License-Identifier: Apache-2.0
+"""Facade for APPXC build utilities"""
+
+# TODO: when growing, this module also include other development tools and need
+# renaming.

appxc/build/pyinstaller.py

@@ -0,0 +1,409 @@
+# Copyright 2026 the contributors of APPXC (github.com/alexander-nbg/appxc)
+# SPDX-License-Identifier: Apache-2.0
+"""Cross-platform PyInstaller build script.
+
+This script provides a unified way to build Python applications using PyInstaller
+across different platforms (Linux, Windows, macOS). It handles virtual environment
+creation, dependency installation, and packaging.
+"""
+
+import argparse
+import platform
+import shutil
+import subprocess
+import sys
+import time
+import traceback
+from pathlib import Path
+
+# Build directory paths (module-level constants)
+BUILD_DIR = Path("./build")
+ENV_PATH = BUILD_DIR / ".env"
+DIST_PATH = BUILD_DIR / "dist"
+
+
+def elapsed_time(start: float) -> str:
+    """Return elapsed time in seconds with one decimal place."""
+    return f"{time.time() - start:.1f}s"
+
+
+class _StepLogger:
+    """Context manager for logging build steps with timing."""
+
+    def __init__(self, message: str):
+        self.message = message
+        self.start_time = None
+
+    def __enter__(self):
+        print(f"\n{'=' * 60}")
+        print(self.message)
+        print(f"{'-' * 60}")
+        self.start_time = time.time()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if exc_type is None:
+            print(f"{'-' * 60}")
+            print(f"Done ({elapsed_time(self.start_time)}); {self.message}")
+            print(f"{'=' * 60}")
+        return False
+
+
+def _run_command(
+    cmd: list[str],
+    shell: bool = False,
+    check: bool = True,
+    verbose: bool = False,
+    **kwargs,
+) -> subprocess.CompletedProcess:
+    """Run a command and return the result."""
+    if verbose:
+        print(f"Running: {' '.join(cmd)}")
+
+    # Suppress output unless verbose or capture_output is set
+    should_capture = not verbose and "capture_output" not in kwargs
+
+    run_kwargs = {
+        "shell": shell,
+        **kwargs,
+    }
+    if should_capture:
+        run_kwargs["capture_output"] = True
+        run_kwargs["text"] = True
+
+    result = subprocess.run(cmd, check=check, **run_kwargs)  # noqa: S603 cmd originating from internal function.
+
+    # Only print if there's an error or warning
+    if should_capture and result.stderr:
+        print(result.stderr, file=sys.stderr)
+
+    return result
+
+
+def create_venv(cleanup: bool = False, verbose: bool = False) -> None:
+    """Create a virtual environment at ./build/.env"""
+    # Remove existing environment if cleanup is requested
+    if cleanup and ENV_PATH.exists():
+        print(f"  Cleaning: Removing existing environment at {ENV_PATH}")
+        shutil.rmtree(ENV_PATH)
+
+    # Create parent directory
+    ENV_PATH.parent.mkdir(parents=True, exist_ok=True)
+
+    # Use system default Python
+    if not ENV_PATH.exists():
+        _run_command(["python", "-m", "venv", str(ENV_PATH)], verbose=verbose)
+        print(f"  Virtual environment created at {ENV_PATH}")
+    else:
+        print(f"  Virtual environment already exists at {ENV_PATH}")
+
+
+def get_activation_script() -> str:
+    """Get the activation script command for the virtual environment."""
+    if platform.system() == "Windows":
+        return str(ENV_PATH / "Scripts" / "activate.bat")
+    return f"source {ENV_PATH / 'bin' / 'activate'}"
+
+
+def _run_in_venv(
+    cmd: list[str],
+    verbose: bool = False,
+    **kwargs,
+) -> subprocess.CompletedProcess:
+    """Run a command within the virtual environment."""
+    # Use the full path to the venv executables (works on all platforms)
+    if platform.system() == "Windows":
+        venv_bin = ENV_PATH / "Scripts"
+        exe_suffix = ".exe"
+    else:
+        venv_bin = ENV_PATH / "bin"
+        exe_suffix = ""
+
+    # Replace python/pip/pyinstaller with full venv path
+    if cmd[0] in ["python", "pip", "pyinstaller"]:
+        cmd[0] = str(venv_bin / f"{cmd[0]}{exe_suffix}")
+
+    return _run_command(cmd, verbose=verbose, **kwargs)
+
+
+def install_requirements(
+    requirements_files: list[Path],
+    editable_packages: list[Path],
+    verbose: bool = False,
+) -> None:
+    """Install requirements in the virtual environment."""
+    # Install requirements files
+    for req_file in requirements_files:
+        if req_file.exists():
+            print(f"  Installing from {req_file}")
+            _run_in_venv(["pip", "install", "-r", str(req_file)], verbose=verbose)
+        else:
+            print(f"  Warning: Requirements file {req_file} not found, skipping")
+
+    # Install editable packages
+    for package in editable_packages:
+        if package.exists():
+            print(f"  Installing editable package from {package}")
+            _run_in_venv(["pip", "install", "-e", str(package)], verbose=verbose)
+        else:
+            print(f"  Warning: Editable package path {package} not found, skipping")
+
+    # Install PyInstaller
+    print("  Installing PyInstaller")
+    _run_in_venv(["pip", "install", "pyinstaller"], verbose=verbose)
+
+
+def build(
+    main_file: Path,
+    debug_build: bool = False,
+    hidden_imports: list[str] | None = None,
+    strip: bool = True,
+    verbose: bool = False,
+) -> None:
+    """Build executable via PyInstaller"""
+    # Base command
+    cmd = [
+        "python",
+        "-m",
+        "PyInstaller",
+        str(main_file),
+        "--onefile",
+        "--clean",
+    ]
+
+    # Add hidden imports
+    if hidden_imports:
+        for imp in hidden_imports:
+            cmd.extend(["--hidden-import", imp])
+
+    # Add strip option (only for Linux/macOS)
+    if strip and platform.system() != "Windows":
+        cmd.append("--strip")
+
+    # Add debug options
+    if debug_build:
+        cmd.extend(["--debug", "all"])
+        cmd.extend(["--name", f"{main_file.stem}_debug"])
+
+    # Set dist path
+    cmd.extend(["--distpath", str(DIST_PATH)])
+
+    _run_in_venv(cmd, verbose=verbose)
+
+
+def copy_additional_files(files: list[Path]) -> None:
+    """Copy additional files to the dist directory."""
+    DIST_PATH.mkdir(parents=True, exist_ok=True)
+
+    for file_path in files:
+        if file_path.exists():
+            dest = DIST_PATH / file_path.name
+            print(f"  Copying {file_path} -> {dest}")
+            shutil.copy2(file_path, dest)
+        else:
+            print(f"  Warning: File {file_path} not found, skipping")
+
+
+def save_build_info(verbose: bool = False) -> None:
+    """Save Python version and package information."""
+    DIST_PATH.mkdir(parents=True, exist_ok=True)
+    info_file = DIST_PATH / "python_versions.txt"
+
+    with open(info_file, "w") as f:
+        # Get Python version
+        result = _run_in_venv(
+            ["python", "--version"],
+            capture_output=True,
+            text=True,
+            verbose=verbose,
+        )
+        f.write(result.stdout)
+
+        # Get pip freeze
+        result = _run_in_venv(
+            ["pip", "freeze"],
+            capture_output=True,
+            text=True,
+            verbose=verbose,
+        )
+        f.write(result.stdout)
+
+    print(f"  Build information saved to {info_file}")
+
+
+def main():
+    """Main entry point"""
+    parser = argparse.ArgumentParser(
+        description="APPXC PyInstaller build script",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  %(prog)s --main-file app.py
+  %(prog)s -m app.py --additional-files data.csv config.ini
+  %(prog)s -m app.py -a template.xlsx --clean --verbose
+  %(prog)s -m app.py --hidden-imports babel.numbers --no-strip
+
+Build outputs:
+  - Virtual environment: ./build/.env
+  - Distribution files: ./build/dist/
+        """,
+    )
+
+    # Mandatory arguments
+    parser.add_argument(
+        "-m",
+        "--main-file",
+        required=True,
+        type=Path,
+        help="Main Python file to build",
+    )
+
+    # Optional arguments
+    parser.add_argument(
+        "-a",
+        "--additional-files",
+        type=Path,
+        nargs="*",
+        default=[],
+        help="Additional files to copy to dist directory",
+    )
+    parser.add_argument(
+        "-r",
+        "--requirements",
+        type=Path,
+        nargs="*",
+        default=[],
+        help=("Additional requirements files to install (default: requirements.txt)"),
+    )
+    parser.add_argument(
+        "--editable-packages",
+        type=Path,
+        nargs="*",
+        default=[],
+        help="Paths to packages to install in editable mode (default: appxc)",
+    )
+    parser.add_argument(
+        "--hidden-imports",
+        nargs="*",
+        default=[],
+        help="Hidden imports for PyInstaller",
+    )
+    parser.add_argument(
+        "--no-strip",
+        action="store_true",
+        help="Disable strip option for PyInstaller",
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Also create a debug build",
+    )
+    parser.add_argument(
+        "--clean",
+        action="store_true",
+        help="Clean build directory before building",
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Show detailed command output",
+    )
+
+    args = parser.parse_args()
+
+    # Convert to absolute paths
+    main_file = args.main_file.resolve()
+
+    # Set default requirements if none provided
+    requirements_files = args.requirements or [
+        Path("requirements.txt"),
+    ]
+
+    # Set default editable packages if none provided
+    editable_packages = args.editable_packages or [
+        Path("appxc"),
+    ]
+
+    print(f"{'=' * 60}")
+    print("PyInstaller Build Script")
+    print(f"{'=' * 60}")
+    print(f"Platform: {platform.system()}")
+    print(f"Main file: {main_file}")
+    print("Build directory: ./build/")
+    print(f"Clean build: {args.clean}")
+    print(f"Verbose: {args.verbose}")
+    print(f"{'=' * 60}")
+
+    # Validate main file exists
+    if not main_file.exists():
+        print(f"Error: Main file {main_file} not found!")
+        sys.exit(1)
+
+    start_total = time.time()
+
+    try:
+        # Clean build directory if requested
+        if args.clean and BUILD_DIR.exists():
+            print(f"\nCleaning build directory: {BUILD_DIR}")
+            shutil.rmtree(BUILD_DIR)
+
+        # Create virtual environment
+        with _StepLogger("Creating virtual environment"):
+            create_venv(cleanup=args.clean, verbose=args.verbose)
+
+        # Install requirements
+        with _StepLogger("Installing requirements"):
+            install_requirements(
+                requirements_files,
+                editable_packages,
+                verbose=args.verbose,
+            )
+
+        # Build with PyInstaller (release)
+        with _StepLogger("Building release version with PyInstaller"):
+            build(
+                main_file,
+                debug_build=False,
+                hidden_imports=args.hidden_imports or None,
+                strip=not args.no_strip,
+                verbose=args.verbose,
+            )
+
+        # Build debug version if requested
+        if args.debug:
+            with _StepLogger("Building debug version with PyInstaller"):
+                build(
+                    main_file,
+                    debug_build=True,
+                    hidden_imports=args.hidden_imports or None,
+                    strip=not args.no_strip,
+                    verbose=args.verbose,
+                )
+
+        # Copy additional files
+        if args.additional_files:
+            with _StepLogger("Copying additional files to dist"):
+                copy_additional_files(args.additional_files)
+
+        # Save build info
+        with _StepLogger("Saving build information"):
+            save_build_info(verbose=args.verbose)
+
+        print(f"\n{'=' * 60}")
+        print(
+            f"Build completed successfully! (Total time: {elapsed_time(start_total)})",
+        )
+        print(f"{'=' * 60}")
+
+    except subprocess.CalledProcessError as e:
+        print(f"\nError: Build failed with exit code {e.returncode}")
+        sys.exit(1)
+    except Exception as e:
+        print(f"\nError: {e}")
+
+        traceback.print_exc()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

appxc/config/__init__.py

@@ -0,0 +1,5 @@
+# Copyright 2024-2026 the contributors of APPXC (github.com/alexander-nbg/appxc)
+# SPDX-License-Identifier: Apache-2.0
+"""Facade for APPXC config module"""
+
+from .config import AppxcConfigError, Config

appxc/config/cleanup_parts.py

@@ -0,0 +1,18 @@
+# Copyright 2024-2026 the contributors of APPXC (github.com/alexander-nbg/appxc)
+# SPDX-License-Identifier: Apache-2.0
+
+# TODO: reactivate storing and loading sections as INI files
+
+
+import configparser
+
+
+class ToolConfigParser(configparser.ConfigParser):
+    """Internal helper with predefined settings for ConfigParser()"""
+
+    def __init__(self, **kwargs):
+        # Note that we need to change the comment prefix to something else and
+        # allow "no values" to keep them as keys without values. Other
+        # functions must then ignore the "#" keys.
+        super().__init__(comment_prefixes="/", allow_no_value=True, **kwargs)
+        self.optionxform = str

appxc/config/config.py

@@ -0,0 +1,152 @@
+# Copyright 2024-2026 the contributors of APPXC (github.com/alexander-nbg/appxc)
+# SPDX-License-Identifier: Apache-2.0
+"""Provide Configuration Handling
+
+The configuration concept is accumulating APPXC SettingDict objects as
+sections.
+"""
+
+from collections.abc import Mapping
+from typing import Any
+
+from appxc import logging
+from appxc.setting import SettingDict
+from appxc.storage import RamStorage, Storage
+
+# TODO: config refactoring
+#  1) I need the serialize/deserialize on dictionaries as storable >> to mary
+#     it with a factory
+#   >> Storage does not exist until storing or loading!
+#  2) Same as above based on configparser. Intended is to combine with
+#     unsecured storage but could theoretically be secured.
+#
+# NOTE: (1) and (2) could initially be the same. I do not care much about
+# storage size such I could implement only (1)
+#
+#  3) option config must become section-specific
+#  4) fields must become private
+#  5) get on section must return the same dict as used internally!
+#     !! The options maintaining dict must use appropriate types
+#     ?? Will it become necessary to define the type on option definition
+#     ** It would be nice to configure an option directly on creation
+
+# TODO: support of translations for section naming since they will pop up in
+# menus. Note that this applies likewise to settings in the SettingDict's.
+
+# TODO: Consider enforcing full lower-case (or full upper-case) section names.
+# Currently, this is not fixed and when checking for existing sections, it's
+# never clear whether upper() should be applied. The best solution would be to
+# support the ["this-section" in config] syntax where the implementation
+# handles the intended case-insensitivity the current usage is like
+# ["this-section" in config.sections()]. This problem applies likewise to
+# SettingDict. If touched, it should also consider the translations solution.
+
+# TODO: recover INI file handling:
+#   1) Loading sections from INI file
+#   2) Store all sections to INI file
+#
+# Note: Section-wise INI handling would imply each section providing it's part.
+# But the file is not section-specific.<
+
+
+class AppxcConfigError(Exception):
+    """General config error"""
+
+
+class Config:
+    """Organize configuration settings.
+
+    Configuration typically splits into several sets of properties for USER or
+    tool access related options. A Config object collects those configuration
+    sections (internally as SettingDict objects) and adds some
+    convenience:
+      * load/store of all sections
+      * store/load into one human readable INI file to assist the tool
+        developers. !! Everything including passwords !!
+
+    In an application, it is recommended to initialize the the aplication parts
+    with the APPXC SettingDict's. They are shared by value and can be loaded
+    after initialization.
+    """
+
+    log = logging.get_logger(__name__ + ".Config")
+
+    def __init__(
+        self,
+        default_storage_factory: Storage.Factory | None = None,
+    ):
+        self._default_storage_factory = default_storage_factory
+        self._sections: dict[str, SettingDict] = {}
+
+    @property
+    def sections(self) -> list[str]:
+        """Return list of sections."""
+        return list(self._sections.keys())
+
+    def section(self, section: str) -> SettingDict:
+        """Access a section"""
+        if section not in self._sections:
+            raise AppxcConfigError(
+                f"Cannot access section {section}, it does not exist. "
+                f"Existing are: {self.sections}.",
+            )
+        return self._sections[section]
+
+    def add_section(
+        self,
+        section: str,
+        storage_factory: Storage.Factory | None = None,
+        settings: Mapping[str, Any] | None = None,
+    ) -> SettingDict:
+        """Add section if not yet existing."""
+        # ensure section does not yet exist:
+        if section in self._sections:
+            raise AppxcConfigError(
+                f"Cannot add section {section}, it does already exist.",
+            )
+        # define storage
+        if storage_factory is not None:
+            storage = storage_factory(section)
+        elif self._default_storage_factory is not None:
+            storage = self._default_storage_factory(section)
+        else:
+            storage = RamStorage()
+        # construct section:
+        #  * SettingDict will take over the section name
+        self._sections[section] = SettingDict(
+            storage=storage,
+            settings=settings,
+            name=section,
+        )
+        #  * Config will, by default, not raise exceptions on import when
+        #    a config option is new or missing
+        export_options = SettingDict.ExportOptions(
+            exception_on_new_key=False,
+            exception_on_missing_key=False,
+        ).get_state()
+        self._sections[section].get_state_kwargs = {"options": export_options}
+        self._sections[section].set_state_kwargs = {"options": export_options}
+
+        self.log.info("added section: %s", section)
+        return self._sections[section]
+
+    def remove_section(self, section: str):
+        """Remove section"""
+        if section in self._sections:
+            del self._sections[section]
+            self.log.info("removed section: %s", section)
+        else:
+            raise AppxcConfigError(
+                f"Cannot remove section, it does not exist: {section}",
+            )
+
+    def store(self):
+        """Store all sections"""
+        for section in self._sections.values():
+            section.store()
+
+    def load(self):
+        """Load all sections"""
+        for section in self._sections.values():
+            if section.exists():
+                section.load()

appxc/email/__init__.py

@@ -0,0 +1,3 @@
+# Copyright 2026 the contributors of APPXC (github.com/alexander-nbg/appxc)
+# SPDX-License-Identifier: Apache-2.0
+"""Facade for APPXC email module"""