installerpack 0.1.0

InstallerPack is a Python module designed to simplify adding 'Installer' functionality to Python applications. It provides a single function that can be linked to button clicks, enabling cloud-based version updates and seamless rebuilding with `pyinstaller`.

Overview

InstallerPack is a Python module designed to simplify updating and distributing Python applications. It mainly:

1. Downloads application versions stored in OctaStore (a cloud-based version storage system).
2. Determines the latest or requested version.
3. Builds a standalone executable using PyInstaller.
4. Optionally replaces an existing executable or places it in a specified folder.

Essentially, it’s a Python “installer/updater” helper.

---

Main Components

1. Initialization and Config

• CAN_USE is a flag to indicate if InstallerPack is ready to operate.

• OctaConfig: a dataclass that stores configuration for OctaStore:

  • tokens, owners, repos — credentials and repos to access.
  • branch, app_name, path_prefix — where the app versions are stored.
  • encryption_key, use_cli_fallback — optional security and fallback options.

_OCTACONF: Optional[OctaConfig] = None  # module-level config

• init() — prints credits and sets CAN_USE = True.
• setocta(conf) — validates and sets the OctaStore configuration.

---

2. Version Handling

InstallerPack supports multiple versioning schemes:

• Semver: 1.2.3 or 1.2.3-alpha
• Calver: YYYY.MM.DD or YYYY.MM
• Sequence version: numbers like 001, 002
• Zero-based version (ZERVER)

Functions:

• parse_semver(v), parse_calver(v), parse_seq(v) — convert version strings into tuples for comparison.
• version_key(v, style) — returns a sortable key based on version style.
• compare_versions(a, b, style) — compares two versions: returns -1, 0, or 1.

This allows InstallerPack to determine the latest version or prevent downgrades.

---

3. OctaStore Helpers

These functions interact with the cloud storage:

• _build_repo_path_for_version(version, conf) — determines path in repo for a version.
• _list_versions_via_api(conf) — tries to list versions using Python API.
• _list_versions_via_cli(conf) — fallback using CLI if Python API fails.
• _download_version_files(conf, version, dest) — downloads the version’s files locally, trying Python API first, then CLI.

Essentially, these functions make InstallerPack cloud-aware, and able to fetch any version of your app automatically.

---

4. PyInstaller Helpers

InstallerPack can build standalone executables:

• _generate_spec(main_script, dest_spec, ...) — creates a .spec file for PyInstaller automatically.
• _run_pyinstaller(spec_path, main_script, ...) — runs PyInstaller, finds the executable, and returns its path.

This allows automatic building of a distributable .exe (or executable) from the downloaded version.

---

5. The update() Function

This is the main public function, designed to be linked to a GUI button or CLI action.

Steps performed by update():

1. Determine version style (SEMVER by default).

2. Ensure OctaStore configuration is set.

3. List available versions from OctaStore.

4. Choose the version to install:

   • "latest" → pick the newest version.
   • Specific version → find closest match.

5. Compare with currentver to prevent unnecessary upgrades/downgrades.

6. Download the version files into a temporary directory.

7. Determine the main Python script to build:

   • Looks for <app_name>.py, main.py, app.py, or first .py recursively.

8. Optionally generate a PyInstaller .spec file (buildspec=True).

9. Run PyInstaller to produce executable.

10. Place or replace the executable in the target folder (landingfolder).

11. Clean up temporary files and spec files.

12. Return a summary dictionary with info:

{
    "updated": True,
    "version": "0.1.0",
    "downloaded_to": "/tmp/installerpack_XXXX",
    "main_script": "/tmp/installerpack_XXXX/main.py",
    "exe": "/target/folder/MyApp.exe"
}

---

Key Design Choices

• Fallbacks: If Python API fails, CLI is used for listing/downloading versions.
• Safety: Prevents downgrades and checks existing versions.
• Heuristics: Tries to detect main script automatically.
• Temporary workspace: Downloads are isolated in temp directories.

---

Usage Example

from installerpack import init, setocta, OctaConfig, update

init()

setocta(OctaConfig(
    tokens=["ghp_xxx"],
    owners=["user"],
    repos=["repo"],
    branch="main",
    app_name="MyApp",
    path_prefix="apps"
))

update(currentver="0.1.0", newver="latest", buildspec=True, landingfolder="C:/MyApps")

This will fetch the latest version from OctaStore, build it, and place the executable in C:/MyApps.

---

✅ In short

InstallerPack is a Python cloud-aware installer/updater framework:

• Connects to OctaStore to get versions.
• Supports multiple versioning schemes.
• Automatically builds executables via PyInstaller.
• Handles version comparison, downloads, and installation intelligently.
• Provides both API and CLI fallbacks.