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`.
License: MIT
Requires Python: >=3.6

## **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.

```python
_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:

```python
{
    "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**

```python
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.