poks 0.3.0

A lightweight archive downloader for pre-built binary dependencies.

Poks

---

Source Code: https://github.com/cuinixam/poks

---

A lightweight, cross-platform archive downloader for pre-built binary dependencies. Inspired by Scoop, Poks provides a uniform way to install and manage developer tools using simple JSON manifests.

While Poks includes a CLI, its main purpose is to be used programmatically to manage dependencies in your Python projects and automation scripts.

Features

• Programmatic API: First-class Python support for integrating into your tools
• Cross-Platform: Works on Windows, Linux, and macOS
• No Admin Rights: Installs tools in user space
• Deterministic: Pin exact versions in manifests for reproducible builds
• Relocatable: The apps directory is self-contained and portable

Installation

Install via pip (or your favorite package manager):

pip install poks

Programmatic Usage

Poks is designed to be easily integrated into your Python scripts.

Quick Start

from pathlib import Path
from poks.poks import Poks

# Initialize Poks with a root directory for apps/cache
poks = Poks(root_dir=Path("./.tools"))

# Install a specific application
# (Automatically searches configured buckets)
poks.install_app("cmake@3.28.1")

# Install from a configuration file (poks.json)
poks.install(Path("poks.json"))

# Uninstall
poks.uninstall(app_name="cmake", version="3.28.1")

CLI Usage

You can also use Poks from the command line.

Installation (CLI)

Install via pipx:

pipx install poks

Quick Start

Create a poks.json configuration file:

{
    "buckets": [
        {
            "name": "main",
            "url": "https://github.com/poks/main-bucket.git"
        }
    ],
    "apps": [
        {
            "name": "cmake",
            "version": "3.28.1",
            "bucket": "main"
        }
    ]
}

Install the defined tools:

poks install -c poks.json

CLI Reference

# Install tools from config file
poks install -c poks.json

# Install a specific tool
poks install zephyr-sdk@0.16.5-1 --bucket main

# Uninstall a specific version
poks uninstall zephyr-sdk@0.16.5-1

# Uninstall all versions of an app
poks uninstall zephyr-sdk

# Uninstall everything
poks uninstall --all

Documentation

For detailed specifications and manifest format, see docs/specs.md.

Contributing

We welcome contributions! Please see our development guidelines below.

Setup and Development

This project uses pypeline for build automation and uv for dependency management.

1. Install Prerequisites: Ensure you have Python 3.10+ and uv installed. pypeline will automatically use uv to create virtual environments.

2. Install Pypeline:

   uv tool install pypeline-runner
   

3. Run the Pipeline: The pipeline handles environment setup, linting, and testing.

   # Run full pipeline (lint + tests)
   pypeline run
   
   # Run only linting (pre-commit hooks)
   pypeline run --step PreCommit
   
   # Run tests with specific Python version
   pypeline run --step CreateVEnv --step PyTest --single --input python_version=3.13
   

AI Agents

For AI agents contributing to this project, please explicitly read and follow AGENTS.md for detailed instructions on workflows, coding standards, and verification steps.

Credits

This package was created with Copier and the browniebroke/pypackage-template project template.