Feature: Add pipx origin (global Python packages) (#341)

Author: Zweih

README.md

@@ -48,7 +48,9 @@ this package is compatible with the following plaforms and distributions:
  - [elementary OS](https://elementary.io/)
  - the 50 other arch and debian-based distros, as long as they have `pacman`, `apt`, `brew`,`dpkg`, or `opkg` installed
 
-`qp` also runs on embedded linux systems, including meta-distributions like [yocto](https://www.yoctoproject.org/) that use `opkg` (`.ipk` packages) or `apt`/`dpkg` (`.deb` packages). `rpm` support is currently on the way! 
+`qp` also detects and queries application-specific package managers like `pipx` for isolated python applications, expanding package discovery beyond traditional system package management.
+
+`qp` supports embedded linux systems, including meta-distributions like [yocto](https://www.yoctoproject.org/) that use `opkg` (`.ipk` packages) or `apt`/`dpkg` (`.deb` packages). `rpm` support is currently on the way! 
 
 more distros and non-linux platforms are planned!
 
@@ -57,7 +59,10 @@ more distros and non-linux platforms are planned!
 * list installed packages across supported systems
 * compatible with macOS, arch, debian, openwrt, and over 60 distros
 * * supports multiple ecosystems:
-  * pacman, dpkg/apt, opkg, brew (formulae, bottles, casks)
+  * system package managers:
+    * pacman, apt/dpkg, opkg, brew
+* * application package managers:
+    * pipx
 * query packages using an expressive query language
   * supports full boolean logic (`and`, `or`, `not`, grouping)
   * supports fuzzy and strict matching
@@ -291,14 +296,13 @@ qp [command] [args] [options]
 - `name` - package name
 - `reason` - installation reason (explicit/dependency)
 - `version` - installed package version
-- `origin` - the package ecosystem or source the package belongs to (e.g., pacman); reflects which package manager or backend maintains it
+- `origin` - the package ecosystem or source the package belongs to (e.g., brew, pipx); reflects which package manager or backend maintains it
 - `arch` - architecture the package was built for (e.g., x86_64, aarch64, any)
 - `license` - package software license
 - `description` - package description
 - `url` - the URL of the official site of the software being packaged
 - `validation` - package integrity validation method (e.g., sha256, pgp)
-- `pkgtype` - package type (pkg, split, debug, src)
-    - ***note**: older packages may have no pkgtype if built before pacman introduced XDATA
+- `pkgtype` - package type (specific to each origin, some origins have no pkgtype)
 - `pkgbase` - name of the base package used to group split packages; for non-split packages, it is the same as the package name. 
 - `packager` - person/entity who built the package (if available)
 - `groups` - list of package groups or categories (e.g., base, gnome, xfce4)
@@ -310,6 +314,24 @@ qp [command] [args] [options]
 - `optional-for` - list of packages that optionally depend on the package (optionally dependent)
 - `provides` - list of alternative package names or shared libraries provided by package
 
+## package types by origin
+
+the `pkgtype` field indicates the type or category of package within each ecosystem. different origins use different package type classifications:
+
+| origin | supported package types | description |
+|--------|------------------------|-------------|
+| pacman | `pkg`, `split`, `debug`, `src` | package build type |
+| brew | `formula`, `cask` | formulae are command-line tools, casks are GUI applications |
+| deb | none | debian packages do not have a pkgtype classification |
+| opkg | none | openwrt packages do not have a pkgtype classification |
+| pipx | none | pipx packages do not have a pkgtype classification |
+
+**notes:**
+- pacman's pkgtype comes from the package's XDATA field introduced in newer pacman versions
+    - older packages may not have this field populated
+- brew distinguishes between formulae (CLI tools/libraries) and casks (GUI applications)
+- deb, opkg, and pipx origins do not implement package type classifications and will show empty pkgtype values
+
 ### querying with `where`
 
 the `where` (short: `w`) command is the core of qp's flexible query system.
@@ -410,7 +432,6 @@ qp w not arch=x86_64
 qp w q has:depends or has:required-by p and not reason=explicit
 ```
 
-
 #### field types
 
 | field type | description |
@@ -778,6 +799,11 @@ output format:
    qp where no:depends
    ```
 
+39. show all packages installed via pipx
+   ```
+   qp where origin=pipx
+   ```
+
 ## license
 
 this project is licensed under GPL-3.0-only.

internal/config/help.go

@@ -98,7 +98,10 @@ Tips:
       qp --no-headers select name,size
 
   - JSON output:
-      qp select name,version,size --json
+      qp select name,version,size --output=json
+
+  - Key-Value output (ideal for selecting all fields):
+     qp s all --output=kv
 
   - Quote arguments with spaces or special characters:
       qp where description="for tree-sitter"

internal/consts/origins.go

@@ -5,4 +5,5 @@ const (
 	OriginPacman = "pacman"
 	OriginDeb    = "deb"
 	OriginOpkg   = "opkg"
+	OriginPipx   = "pipx"
 )

internal/origins/drivers/brew/fetch_casks.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"qp/internal/origins/shared"
 	"qp/internal/origins/worker"
 	"qp/internal/pkgdata"
 	"sync"
@@ -66,7 +67,7 @@ func fetchCasks(
 		errChan,
 		errGroup,
 		func(pkg *pkgdata.PkgInfo) (*pkgdata.PkgInfo, error) {
-			size, err := getInstallSize(filepath.Join(caskroomRoot, pkg.Name, pkg.Version))
+			size, err := shared.GetInstallSize(filepath.Join(caskroomRoot, pkg.Name, pkg.Version))
 			if err == nil {
 				pkg.Size = size
 			}

internal/origins/drivers/brew/fetch_formulae.go

@@ -2,6 +2,7 @@ package brew
 
 import (
 	"path/filepath"
+	"qp/internal/origins/shared"
 	"qp/internal/origins/worker"
 	"qp/internal/pkgdata"
 	"sync"
@@ -76,7 +77,7 @@ func fetchFormulae(
 		errGroup,
 		func(pkg *pkgdata.PkgInfo) (*pkgdata.PkgInfo, error) {
 			versionPath := filepath.Join(prefix, cellarSubPath, pkg.Name, pkg.Version)
-			if size, err := getInstallSize(versionPath); err == nil {
+			if size, err := shared.GetInstallSize(versionPath); err == nil {
 				pkg.Size = size
 			}
 

internal/origins/drivers/deb/parser.go

@@ -5,7 +5,7 @@ import (
 	"errors"
 	"fmt"
 	"qp/internal/consts"
-	"qp/internal/origins/formats/debstyle"
+	"qp/internal/origins/shared/debstyle"
 	"qp/internal/origins/worker"
 	"qp/internal/pkgdata"
 	"strconv"

internal/origins/drivers/opkg/parser.go

@@ -7,7 +7,7 @@ import (
 	"os"
 	"path/filepath"
 	"qp/internal/consts"
-	"qp/internal/origins/formats/debstyle"
+	"qp/internal/origins/shared/debstyle"
 	"qp/internal/origins/worker"
 	"qp/internal/pkgdata"
 	"strconv"

internal/origins/drivers/pipx/constants.go

@@ -0,0 +1,23 @@
+package pipx
+
+const (
+	defaultVenvRoot = ".local/pipx/venvs"
+	otherVenvRoot   = ".local/share/pipx/venvs"
+
+	fieldName        = "Name"
+	fieldVersion     = "Version"
+	fieldSummary     = "Summary"
+	fieldLicense     = "License"
+	fieldHomepage    = "Home-page"
+	fieldProjectUrl  = "Project-Url"
+	subfieldHomepage = "Homepage"
+	fieldTag         = "Tag"
+
+	anyArch       = "any"
+	universalArch = "universal"
+
+	dotDistInfo = ".dist-info"
+
+	pipxHomeEnv = "PIPX_HOME"
+	homeEnv     = "HOME"
+)

internal/origins/drivers/pipx/discover.go

@@ -0,0 +1,92 @@
+package pipx
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+func findVenvRoot() (string, error) {
+	var venvRootPath string
+
+	if custom := os.Getenv(pipxHomeEnv); custom != "" {
+		venvRootPath = filepath.Join(custom, "venvs")
+		_, err := os.Stat(venvRootPath)
+		if err == nil {
+			return venvRootPath, nil
+		}
+	}
+
+	home, err := os.UserHomeDir()
+	if err != nil {
+		home = os.Getenv(homeEnv)
+	}
+
+	possibleRoots := []string{defaultVenvRoot, otherVenvRoot}
+	for _, root := range possibleRoots {
+		venvRootPath = filepath.Join(home, root)
+		_, err := os.Stat(venvRootPath)
+		if err == nil {
+			return venvRootPath, nil
+		}
+	}
+
+	return "", errors.New("no pipx venv root found")
+}
+
+func findVersionPath(libRoot string) (string, error) {
+	entries, err := os.ReadDir(libRoot)
+	if err != nil {
+		return "", err
+	}
+
+	for _, entry := range entries {
+		if entry.IsDir() && len(entry.Name()) > 6 && entry.Name()[:6] == "python" {
+			return filepath.Join(libRoot, entry.Name()), nil
+		}
+	}
+
+	return "", fmt.Errorf("no pythonX.Y found under %s", libRoot)
+}
+
+func findDistPath(sitePkgsPath string, name string) (string, error) {
+	distInfoMatcher := name + "-*" + dotDistInfo
+	matches, _ := filepath.Glob(filepath.Join(sitePkgsPath, distInfoMatcher, "METADATA"))
+	if len(matches) > 0 {
+		return matches[0], nil
+	}
+
+	return "", fmt.Errorf("no .dist-info/METADATA found for: %s", name)
+}
+
+func inferArchitecture(sitePkgsPath string) (string, error) {
+	distInfoMatcher := "*" + dotDistInfo
+	matches, err := filepath.Glob(filepath.Join(sitePkgsPath, distInfoMatcher, "WHEEL"))
+	if err != nil {
+		return "", fmt.Errorf("found no .dist-info directories in %s: %v", sitePkgsPath, err)
+	}
+
+	bestMatch := anyArch
+
+	for _, match := range matches {
+		arch, err := parseWheelFile(match)
+		if err != nil {
+			continue
+		}
+
+		parts := strings.Split(arch, "-")
+		suffix := parts[len(parts)-1]
+
+		if suffix != anyArch {
+			if !strings.Contains(suffix, universalArch) {
+				return suffix, nil
+			}
+
+			bestMatch = suffix
+		}
+	}
+
+	return bestMatch, nil
+}

internal/origins/drivers/pipx/driver.go

@@ -0,0 +1,45 @@
+package pipx
+
+import (
+	"qp/internal/consts"
+	"qp/internal/origins/shared"
+	"qp/internal/pkgdata"
+)
+
+type PipxDriver struct {
+	venvRoot string
+}
+
+func (d *PipxDriver) Name() string {
+	return consts.OriginPipx
+}
+
+func (d *PipxDriver) Detect() bool {
+	venvRoot, err := findVenvRoot()
+	if err != nil {
+		return false
+	}
+
+	d.venvRoot = venvRoot
+	return true
+}
+
+func (d *PipxDriver) Load() ([]*pkgdata.PkgInfo, error) {
+	return fetchPackages(d.venvRoot, d.Name())
+}
+
+func (d *PipxDriver) ResolveDeps(pkgs []*pkgdata.PkgInfo) ([]*pkgdata.PkgInfo, error) {
+	return pkgs, nil
+}
+
+func (d *PipxDriver) LoadCache(path string) ([]*pkgdata.PkgInfo, error) {
+	return pkgdata.LoadProtoCache(path)
+}
+
+func (d *PipxDriver) SaveCache(cacheRoot string, pkgs []*pkgdata.PkgInfo) error {
+	return pkgdata.SaveProtoCache(cacheRoot, pkgs)
+}
+
+func (d *PipxDriver) IsCacheStale(cacheMtime int64) (bool, error) {
+	return shared.BfsStale(d.venvRoot, cacheMtime, 2)
+}