kpip 0.0.1__tar.gz

kpip-0.0.1/.gitattributes

@@ -0,0 +1 @@
+tools/vendoring/patches/*.patch -whitespace

kpip-0.0.1/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [KRRT7]

kpip-0.0.1/.github/workflows/checks.yml

@@ -0,0 +1,100 @@
+name: Checks
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+env:
+  # Keep failures readable: pytest's own progress output is enough, and a
+  # traceback per failure beats a screenful of locals.
+  PYTEST_ADDOPTS: "--color=yes -q --tb=short"
+
+jobs:
+  lint:
+    name: Lint and types
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        with:
+          enable-cache: true
+      # Type checking traverses optional integrations that are exercised by
+      # the test suite, so make their importable packages available too.
+      - run: uv sync --locked --group typing --group test
+      - name: ruff check
+        run: uv run ruff check src tests conftest.py
+      - name: ruff format
+        run: uv run ruff format --check src tests conftest.py
+      - name: ty
+        run: uv run ty check src
+
+  tests:
+    name: Tests / Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        with:
+          enable-cache: true
+      - name: Install Subversion
+        run: sudo apt-get update && sudo apt-get install --yes subversion
+      - run: uv sync --locked --group test
+      - name: Unit and package tests
+        # Excludes tests/cli/functional, which drives a real kpip in a
+        # subprocess and runs in its own job below. Network-marked tests are
+        # deselected here so a slow index cannot fail an unrelated pull
+        # request; the functional job covers what needs the network.
+        run: >
+          uv run pytest tests
+          --ignore=tests/cli/functional
+          --ignore=tests/benchmarks
+          -m "not network"
+          -p no:randomly
+
+  functional:
+    name: Functional / Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # setup-python does not publish 3.15 builds yet. Keep the minimum and
+        # newest available supported interpreter as the functional gates.
+        python-version: ["3.10", "3.14"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        with:
+          enable-cache: true
+      - name: Install Subversion
+        run: sudo apt-get update && sudo apt-get install --yes subversion
+      - run: uv sync --locked --group test
+      - name: Functional tests
+        run: uv run pytest tests/cli/functional -n auto

kpip-0.0.1/.github/workflows/codspeed.yml

@@ -0,0 +1,39 @@
+name: CodSpeed
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  # Allows CodSpeed to trigger backtest performance analysis.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  benchmarks:
+    name: CodSpeed / Python 3.12
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write # OpenID Connect authentication with CodSpeed
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        with:
+          enable-cache: true
+      - run: uv sync --locked --all-groups
+      - name: Run benchmarks
+        uses: CodSpeedHQ/action@88472375d0a4572cf70a9f1fe3a4e0ab8da1b924 # v5.0.1
+        with:
+          mode: simulation
+          run: uv run pytest tests/benchmarks --codspeed

kpip-0.0.1/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+.venv/
+/build/
+# The package's build module is source code, not the root build output.
+!src/kpip/build/
+dist/
+*.egg-info/
+
+# Recorded kpip-bench baselines (kpip-bench-record).
+benchmark-runs/

kpip-0.0.1/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2008-present The kpip developers
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

kpip-0.0.1/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: kpip
+Version: 0.0.1
+License-Expression: MIT
+License-File: LICENSE.txt
+Summary: Pip Reimagined for Performance
+Author-email: Kevin Turcios <turcioskevinr@gmail.com>
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Project-URL: Homepage, https://github.com/warpforgedotco/kpip
+Project-URL: Documentation, https://github.com/warpforgedotco/kpip#readme
+Project-URL: Source, https://github.com/warpforgedotco/kpip
+Description-Content-Type: text/markdown
+Requires-Python: >=3.10
+
+# kpip
+
+[![Checks](https://github.com/warpforgedotco/kpip/actions/workflows/checks.yml/badge.svg)](https://github.com/warpforgedotco/kpip/actions/workflows/checks.yml)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.txt)
+
+**A working reflection of what pip can be when performance engineering is a
+design constraint.**
+
+kpip is a working, performance-engineered interpretation of pip. It brings
+together concrete improvements across startup, resolution, caching, artifact
+handling, and installation into a familiar command model that can be measured,
+tested, and evaluated as a complete system.
+
+The goal is not to establish another permanent package-manager ecosystem. All
+work here is intended to inform, adapt into, and ultimately flow upstream to
+pip.
+
+> [!WARNING]
+> kpip is an early-alpha experimental implementation, published on PyPI for
+> testing and evaluation. It is not a supported pip distribution or a drop-in
+> replacement and should not be used to manage critical or system Python
+> environments. Interfaces, behavior, and cache formats may change.
+
+## Why kpip exists
+
+[pip](https://pip.pypa.io/) established the package-installation workflow that
+Python users know, and it must evolve while serving an enormous compatibility
+surface. [uv](https://github.com/astral-sh/uv) demonstrated how much performance
+headroom exists when packaging is reconsidered end to end.
+
+kpip creates room to explore that headroom in a Python-native implementation,
+while keeping pip's users, semantics, and upstream constraints in view. It asks
+what pip can become when startup, resolution, artifact handling, caching, and
+installation are treated as first-class performance problems.
+
+## Upstream is the destination
+
+kpip now contains a working body of performance engineering intended to flow
+back to pip and the wider Python packaging ecosystem. The current goal is to
+determine how best to upstream that work: identify the improvements that
+transfer cleanly, separate them into focused and reviewable changes, adapt them
+to pip's architecture and compatibility requirements, and validate them in
+pip's own test and benchmark environments.
+
+The repository is not expected to map commit-for-commit onto pip. Its
+implementation combines several architectural changes and, in places, narrows
+compatibility to make performance gains measurable. Upstreaming means
+extracting the underlying ideas and evidence, then reshaping them into changes
+that fit pip's maintenance and compatibility constraints.
+
+Each upstream proposal should carry forward:
+
+- a reproducible measurement of the problem and the improvement;
+- behavioral and compatibility tests that preserve pip's contract;
+- the smallest maintainable implementation that can be proposed upstream; and
+- a clear account of tradeoffs, limitations, and results that did not hold up.
+
+Negative results matter too. If an optimization does not survive realistic
+workloads or cannot preserve behavior, the useful outcome is the evidence—not a
+performance claim.
+
+## Installation
+
+Install kpip from PyPI as an isolated tool with uv:
+
+```console
+uv tool install kpip
+kpip --version
+```
+
+Or run it from a source checkout:
+
+```console
+git clone https://github.com/warpforgedotco/kpip.git
+cd kpip
+uv sync --locked
+uv run kpip --version
+```
+
+## Quick start
+
+Create an environment, then point an isolated kpip installation at it with the
+global `--python` option:
+
+```console
+python -m venv .venv
+kpip --python .venv install httpx
+kpip --python .venv list
+```
+
+Install a requirements file:
+
+```console
+kpip --python .venv install -r requirements.txt
+```
+
+Resolve an input file into `pylock.toml`, then install it:
+
+```console
+kpip lock -r requirements.in
+kpip --python .venv install -r pylock.toml
+```
+
+If kpip is installed inside the environment it should manage, omit
+`--python .venv` and invoke `kpip` directly.
+
+## Commands
+
+| Task | Commands |
+| --- | --- |
+| Install or prepare packages | `install`, `wheel`, `download` |
+| Remove packages | `uninstall` |
+| Inspect an environment | `list`, `freeze`, `show`, `inspect`, `check` |
+| Resolve reproducibly | `lock` |
+| Work with indexes and artifacts | `index`, `hash` |
+| Inspect or clear local state | `cache` |
+
+Run `kpip <command> --help` for command-specific options.
+
+## Benchmarking
+
+The benchmark suite uses [Hyperfine](https://github.com/sharkdp/hyperfine) to
+compare kpip and uv through the same inputs and isolated targets. uv serves as
+an external performance reference; before-and-after kpip runs show whether a
+specific experiment helped. Neither replaces measuring an eventual patch in
+pip's own architecture and test environment. The default offline workload is
+generated locally and avoids network variance.
+
+With `hyperfine` and `uv` available on `PATH`:
+
+```console
+cd scripts/benchmark
+uv sync --locked --group tests
+uv run kpip-bench --workload offline
+```
+
+The harness includes startup, cold and warm locking, cold and warm
+installation, and incremental installation cases. It can also run the
+workloads used by uv's public benchmarks, but those are opt-in because live
+indexes and platform-specific wheels make them less reproducible.
+
+See the [benchmark guide](scripts/benchmark/README.md) for workload selection,
+recording quiet-machine baselines, exporting raw Hyperfine results, and
+comparing two commits. The measurement philosophy follows the
+[X-Ray Performance Laboratory](https://github.com/KRRT7/xray): benchmark first,
+then optimize what the evidence identifies.
+
+## Design
+
+The main path is intentionally layered:
+
+```text
+CLI -> resolution -> candidate discovery -> artifact preparation -> transaction
+```
+
+Each layer owns one part of the package-installation process. Fast paths are
+narrow recognizers that decline to the general implementation whenever they
+cannot preserve the same semantics. Persistent caches are optional: a missing,
+stale, or corrupt entry must become a cache miss rather than a correctness
+failure.
+
+The [architecture guide](docs/architecture.md) maps these boundaries, the
+runtime dependency rules between packages, the resolver flow, and every
+persistent cache.
+
+## Development
+
+Set up the test and typing environments:
+
+```console
+git clone https://github.com/warpforgedotco/kpip.git
+cd kpip
+uv sync --locked --group test --group typing
+```
+
+Run the main local checks:
+
+```console
+uv run ruff check src tests conftest.py
+uv run ruff format --check src tests conftest.py
+uv run ty check src
+uv run pytest tests \
+  --ignore=tests/cli/functional \
+  --ignore=tests/benchmarks \
+  -m "not network"
+```
+
+Functional tests exercise the real CLI in subprocesses:
+
+```console
+uv run pytest tests/cli/functional -n auto
+```
+
+The [checks workflow](.github/workflows/checks.yml) is the source of truth for
+the supported CI matrix. Before proposing a performance change, record a
+comparable before-and-after benchmark; a locally faster microbenchmark is not
+enough on its own. A change is not finished merely because it lands in kpip:
+identify how its implementation, tests, and evidence can move upstream.
+
+## Acknowledgements
+
+kpip exists because of—and in service of—the interfaces, behavior, and testing
+knowledge developed by [pip and PyPA](https://github.com/pypa/pip). It is meant
+to help that work move forward, not to pull users or contributors into a
+permanently separate ecosystem. Its performance experiments also learn from
+the techniques and public workloads in [uv](https://github.com/astral-sh/uv).
+Third-party code shipped with kpip is documented in the [vendoring
+manifest](src/kpip/_vendor/VENDORED.md).
+
+## License
+
+kpip is available under the [MIT License](LICENSE.txt).

kpip-0.0.1/README.md

@@ -0,0 +1,213 @@
+# kpip
+
+[![Checks](https://github.com/warpforgedotco/kpip/actions/workflows/checks.yml/badge.svg)](https://github.com/warpforgedotco/kpip/actions/workflows/checks.yml)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.txt)
+
+**A working reflection of what pip can be when performance engineering is a
+design constraint.**
+
+kpip is a working, performance-engineered interpretation of pip. It brings
+together concrete improvements across startup, resolution, caching, artifact
+handling, and installation into a familiar command model that can be measured,
+tested, and evaluated as a complete system.
+
+The goal is not to establish another permanent package-manager ecosystem. All
+work here is intended to inform, adapt into, and ultimately flow upstream to
+pip.
+
+> [!WARNING]
+> kpip is an early-alpha experimental implementation, published on PyPI for
+> testing and evaluation. It is not a supported pip distribution or a drop-in
+> replacement and should not be used to manage critical or system Python
+> environments. Interfaces, behavior, and cache formats may change.
+
+## Why kpip exists
+
+[pip](https://pip.pypa.io/) established the package-installation workflow that
+Python users know, and it must evolve while serving an enormous compatibility
+surface. [uv](https://github.com/astral-sh/uv) demonstrated how much performance
+headroom exists when packaging is reconsidered end to end.
+
+kpip creates room to explore that headroom in a Python-native implementation,
+while keeping pip's users, semantics, and upstream constraints in view. It asks
+what pip can become when startup, resolution, artifact handling, caching, and
+installation are treated as first-class performance problems.
+
+## Upstream is the destination
+
+kpip now contains a working body of performance engineering intended to flow
+back to pip and the wider Python packaging ecosystem. The current goal is to
+determine how best to upstream that work: identify the improvements that
+transfer cleanly, separate them into focused and reviewable changes, adapt them
+to pip's architecture and compatibility requirements, and validate them in
+pip's own test and benchmark environments.
+
+The repository is not expected to map commit-for-commit onto pip. Its
+implementation combines several architectural changes and, in places, narrows
+compatibility to make performance gains measurable. Upstreaming means
+extracting the underlying ideas and evidence, then reshaping them into changes
+that fit pip's maintenance and compatibility constraints.
+
+Each upstream proposal should carry forward:
+
+- a reproducible measurement of the problem and the improvement;
+- behavioral and compatibility tests that preserve pip's contract;
+- the smallest maintainable implementation that can be proposed upstream; and
+- a clear account of tradeoffs, limitations, and results that did not hold up.
+
+Negative results matter too. If an optimization does not survive realistic
+workloads or cannot preserve behavior, the useful outcome is the evidence—not a
+performance claim.
+
+## Installation
+
+Install kpip from PyPI as an isolated tool with uv:
+
+```console
+uv tool install kpip
+kpip --version
+```
+
+Or run it from a source checkout:
+
+```console
+git clone https://github.com/warpforgedotco/kpip.git
+cd kpip
+uv sync --locked
+uv run kpip --version
+```
+
+## Quick start
+
+Create an environment, then point an isolated kpip installation at it with the
+global `--python` option:
+
+```console
+python -m venv .venv
+kpip --python .venv install httpx
+kpip --python .venv list
+```
+
+Install a requirements file:
+
+```console
+kpip --python .venv install -r requirements.txt
+```
+
+Resolve an input file into `pylock.toml`, then install it:
+
+```console
+kpip lock -r requirements.in
+kpip --python .venv install -r pylock.toml
+```
+
+If kpip is installed inside the environment it should manage, omit
+`--python .venv` and invoke `kpip` directly.
+
+## Commands
+
+| Task | Commands |
+| --- | --- |
+| Install or prepare packages | `install`, `wheel`, `download` |
+| Remove packages | `uninstall` |
+| Inspect an environment | `list`, `freeze`, `show`, `inspect`, `check` |
+| Resolve reproducibly | `lock` |
+| Work with indexes and artifacts | `index`, `hash` |
+| Inspect or clear local state | `cache` |
+
+Run `kpip <command> --help` for command-specific options.
+
+## Benchmarking
+
+The benchmark suite uses [Hyperfine](https://github.com/sharkdp/hyperfine) to
+compare kpip and uv through the same inputs and isolated targets. uv serves as
+an external performance reference; before-and-after kpip runs show whether a
+specific experiment helped. Neither replaces measuring an eventual patch in
+pip's own architecture and test environment. The default offline workload is
+generated locally and avoids network variance.
+
+With `hyperfine` and `uv` available on `PATH`:
+
+```console
+cd scripts/benchmark
+uv sync --locked --group tests
+uv run kpip-bench --workload offline
+```
+
+The harness includes startup, cold and warm locking, cold and warm
+installation, and incremental installation cases. It can also run the
+workloads used by uv's public benchmarks, but those are opt-in because live
+indexes and platform-specific wheels make them less reproducible.
+
+See the [benchmark guide](scripts/benchmark/README.md) for workload selection,
+recording quiet-machine baselines, exporting raw Hyperfine results, and
+comparing two commits. The measurement philosophy follows the
+[X-Ray Performance Laboratory](https://github.com/KRRT7/xray): benchmark first,
+then optimize what the evidence identifies.
+
+## Design
+
+The main path is intentionally layered:
+
+```text
+CLI -> resolution -> candidate discovery -> artifact preparation -> transaction
+```
+
+Each layer owns one part of the package-installation process. Fast paths are
+narrow recognizers that decline to the general implementation whenever they
+cannot preserve the same semantics. Persistent caches are optional: a missing,
+stale, or corrupt entry must become a cache miss rather than a correctness
+failure.
+
+The [architecture guide](docs/architecture.md) maps these boundaries, the
+runtime dependency rules between packages, the resolver flow, and every
+persistent cache.
+
+## Development
+
+Set up the test and typing environments:
+
+```console
+git clone https://github.com/warpforgedotco/kpip.git
+cd kpip
+uv sync --locked --group test --group typing
+```
+
+Run the main local checks:
+
+```console
+uv run ruff check src tests conftest.py
+uv run ruff format --check src tests conftest.py
+uv run ty check src
+uv run pytest tests \
+  --ignore=tests/cli/functional \
+  --ignore=tests/benchmarks \
+  -m "not network"
+```
+
+Functional tests exercise the real CLI in subprocesses:
+
+```console
+uv run pytest tests/cli/functional -n auto
+```
+
+The [checks workflow](.github/workflows/checks.yml) is the source of truth for
+the supported CI matrix. Before proposing a performance change, record a
+comparable before-and-after benchmark; a locally faster microbenchmark is not
+enough on its own. A change is not finished merely because it lands in kpip:
+identify how its implementation, tests, and evidence can move upstream.
+
+## Acknowledgements
+
+kpip exists because of—and in service of—the interfaces, behavior, and testing
+knowledge developed by [pip and PyPA](https://github.com/pypa/pip). It is meant
+to help that work move forward, not to pull users or contributors into a
+permanently separate ecosystem. Its performance experiments also learn from
+the techniques and public workloads in [uv](https://github.com/astral-sh/uv).
+Third-party code shipped with kpip is documented in the [vendoring
+manifest](src/kpip/_vendor/VENDORED.md).
+
+## License
+
+kpip is available under the [MIT License](LICENSE.txt).