uvault 0.2.0__tar.gz

uvault-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Run tests and coverage
+        run: uv run --frozen pytest
+
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - uses: pre-commit/action@v3.0.1

uvault-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/uvault
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          python-version: "3.13"
+          enable-cache: true
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

uvault-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.specs/.thirdparty/
+.specs/
+site/

uvault-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.8 # Matches compatible pre-commit version hook, will auto-update
+    hooks:
+      - id: ruff
+        args: [ --fix ]
+      - id: ruff-format

uvault-0.2.0/.python-version

@@ -0,0 +1 @@
+3.14

uvault-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pierre Verkest
+
+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.

uvault-0.2.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: uvault
+Version: 0.2.0
+Summary: Development and vaulting workflow for uv VCS dependencies.
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: diskcache>=5.6.3
+Requires-Dist: tomlkit>=0.15.0
+Description-Content-Type: text/markdown
+
+# uvault
+
+Development and vaulting workflow for [uv](https://github.com/astral-sh/uv) VCS dependencies.
+
+Secure your Python projects against deleted or force-pushed upstream commits. `uvault` automatically vaults transient VCS references (like GitHub PRs) into your organization's own repositories, while allowing developers to instantly switch dependencies into local editable mode—fully integrated with `pyproject.toml` and `uv`.
+
+## Documentation
+
+The complete documentation is available in the `docs/` folder:
+
+* [Quickstart & Key Features](docs/index.md) - Learn what `uvault` is and how to get started quickly.
+* [How-To Guides](docs/how-to.md) - Step-by-step guides for installing and using `uvault` in your day-to-day workflow.
+* [CLI & Configuration Reference](docs/reference.md) - Detailed information on `pyproject.toml` configuration (`[tool.uvault]`) and all CLI commands (`sync`, `add`, `develop`).

uvault-0.2.0/README.md

@@ -0,0 +1,13 @@
+# uvault
+
+Development and vaulting workflow for [uv](https://github.com/astral-sh/uv) VCS dependencies.
+
+Secure your Python projects against deleted or force-pushed upstream commits. `uvault` automatically vaults transient VCS references (like GitHub PRs) into your organization's own repositories, while allowing developers to instantly switch dependencies into local editable mode—fully integrated with `pyproject.toml` and `uv`.
+
+## Documentation
+
+The complete documentation is available in the `docs/` folder:
+
+* [Quickstart & Key Features](docs/index.md) - Learn what `uvault` is and how to get started quickly.
+* [How-To Guides](docs/how-to.md) - Step-by-step guides for installing and using `uvault` in your day-to-day workflow.
+* [CLI & Configuration Reference](docs/reference.md) - Detailed information on `pyproject.toml` configuration (`[tool.uvault]`) and all CLI commands (`sync`, `add`, `develop`).

uvault-0.2.0/docs/how-to.md

@@ -0,0 +1,84 @@
+# Tutorials / How-To
+
+## How to manage and vault dependencies
+
+`uvault` is built around a typical workflow: declaring a dependency intention, synchronizing it to your vault, and (optionally) switching to local development mode.
+
+### Installation (Recommended)
+
+To get the most out of `uvault`, especially its ability to automatically discover repository URLs via package metadata when using the `uvault add` command, we highly recommend installing it as a development dependency in your project:
+
+```bash
+uv add --dev uvault
+```
+
+By installing it within your project's environment, `uvault` gains access to the local site-packages, allowing it to easily read the metadata of your project's existing dependencies.
+
+### Step 1: Add a new dependency (`uvault add`)
+
+Instead of manually editing the `pyproject.toml` file, use the `uvault add` command to declare an intention in `[tool.uvault.sources]`.
+
+```bash
+uvault add my-addon https://github.com/OCA/my-addon --pr 123 --subdirectory my_addon
+```
+
+If the repository URL is already known (published package), you can omit it and `uvault` will try to guess it from the package metadata:
+```bash
+uvault add my-addon --branch 16.0
+```
+
+*Note: This command only configures your intention. It does not update your `uv` lockfile.*
+
+### Step 2: Synchronize and Vault (`uvault sync`)
+
+Once you have declared your dependencies, run the synchronization command to fetch them and push them to your organization's vault repository.
+
+```bash
+uvault sync
+```
+
+The command will:
+1. Fetch the exact commit of the targeted branch or PR.
+2. Clone this repository into the local cache (if necessary).
+3. Push this commit to your vault repository as a frozen tag (e.g. `ppr-<sha>`).
+4. Automatically update the `[tool.uv.sources]` block in `pyproject.toml` to point to this immutable reference.
+
+**Crucial Step:** After syncing, you must instruct `uv` to resolve the new dependencies:
+```bash
+uv lock
+# or
+uv sync
+```
+
+#### Update an existing reference
+If the original PR has been updated (new commits):
+
+```bash
+uvault sync --update
+```
+
+This will force the retrieval of new changes and update the vault reference. You can also target specific packages (which automatically implies an update):
+
+```bash
+uvault sync --package my-addon
+uvault sync -P my-addon -P another-addon
+```
+
+### Step 3: Develop Locally (`uvault develop`)
+
+When you need to make modifications to a vaulted dependency, you can switch it into local editable mode in seconds.
+
+```bash
+uvault develop my-addon my-feature-branch
+```
+
+This command will:
+1. Clone the repository into your local workspace (e.g., `./.src/my-addon`).
+2. Automatically configure your custom vault remotes (defined in `~/.config/uvault/config.toml`) so you can push your work easily.
+3. Replace the remote reference in `[tool.uv.sources]` with a local, editable path (`editable = true`).
+4. Creates and checks out the new branch (`git checkout -b <branch>`), or simply switches to it if it already exists.
+
+**Crucial Step:** Once the local path is set, make sure to synchronize your environment:
+```bash
+uv sync
+```

uvault-0.2.0/docs/index.md

@@ -0,0 +1,42 @@
+# uvault
+
+Development and vaulting workflow for [uv](https://github.com/astral-sh/uv) VCS dependencies.
+
+Secure your Python projects against deleted or force-pushed upstream commits.
+
+`uvault` automatically vaults transient VCS references (like GitHub PRs)
+into your organization's own repositories, while allowing developers to instantly
+switch dependencies into local editable mode—fully integrated with `pyproject.toml` and `uv`.
+
+## Key Features
+
+1. **Vaulting of Commits**: Never lose code again! Upstream pull requests and branches can be force-pushed or deleted. `uvault` fetches the exact commits your project depends on and pushes them as immutable tags to your own organization's vault repository.
+2. **Easy Local Development**: Switch any VCS dependency to local "editable" mode in seconds. `uvault develop` clones the package locally and seamlessly configures `uv` to use your local copy so you can test changes and contribute back.
+
+## Quickstart
+
+### 1. Add a Dependency
+
+Use `uvault add` to register an intention for a dependency. You can pass a PEP 508 URL or rely on automatic URL guessing if the package is already published.
+
+```bash
+uvault add odoo-addon-my-package https://github.com/OCA/my-repo --pr 123 --subdirectory my_package
+```
+
+### 2. Vault and Lock
+
+Synchronize the dependency with your vault and lock it in `uv`.
+
+```bash
+uvault sync
+uv lock
+```
+
+### 3. Develop Locally
+
+Need to edit the dependency? Clone it instantly and set it as an editable dependency in `[tool.uv.sources]`.
+
+```bash
+uvault develop my-package feat-branch
+uv sync
+```

uvault-0.2.0/docs/reference.md

@@ -0,0 +1,100 @@
+# Reference
+
+## Installation & Usage Modes
+
+`uvault` can be executed in two different ways depending on your needs:
+
+### 1. As a Project Development Dependency (Recommended)
+
+Installing `uvault` as a dev dependency gives it access to your project's environment. This is crucial if you want `uvault add` to automatically guess repository URLs based on the metadata of your installed packages.
+
+```bash
+uv add --dev uvault
+uv run uvault --help
+```
+
+### 2. As an Independent Tool via `uvx`
+
+If you prefer keeping your dependencies minimal and don't need the automatic URL resolution feature, you can run `uvault` purely as an isolated, ephemeral tool using `uvx`.
+
+```bash
+uvx uvault sync
+```
+
+## `pyproject.toml` Configuration
+
+The intention configuration is located in the `[tool.uvault]` section:
+
+```toml
+[tool.uvault]
+tag_prefix = "apycod-"               # (Optional) Prefix for generated tags. Defaults to "".
+include_project_version = true          # (Optional) Includes the current project's version in the vault tag. Defaults to true.
+dev_directory = ".src/"                 # (Optional) Directory for developed sources. Defaults to ".src/".
+
+# VCS Vault Configuration
+[[tool.uvault.vcs_vaults]]
+provider = "github.com"                 # (Required) The git hosting provider (e.g., "github.com" or "gitlab.com").
+owner = "petrus-v"                      # (Optional) The user or organization owning the vault repository.
+fetch_ssh = true                        # (Optional) If true, generates ssh:// URLs in [tool.uv.sources] instead of https://. Defaults to false.
+push_ssh = true                         # (Optional) If true, pushes tags to the vault using ssh://. Defaults to true.
+default = true                          # (Optional) Marks this vault as the default for synchronizing packages.
+
+# Declaration of dependencies to synchronize
+[tool.uvault.sources]
+my-package = { git = "https://github.com/OCA/repository", rev = "refs/pull/100/head", subdirectory = "my_package" }
+```
+
+## User Configuration
+
+You can define local machine-specific configurations, such as custom git remotes, in `~/.config/uvault/config.toml`. These remotes will be automatically added to the repository when running `uvault develop`.
+
+```toml
+[remotes]
+myorg = "https://gitlab.com/myorg/"
+perso = "ssh://git@github.com/personal/"
+```
+
+## CLI Commands
+
+### `uvault sync`
+
+Synchronizes remote references to the vault repository and updates `[tool.uv.sources]`.
+
+**Note:** By default, `uvault sync` will skip any package that is already declared in `[tool.uv.sources]`.
+
+**Flags:**
+* `-P <package>, --package <package>` : Only sync the specified package. Can be used multiple times.
+* `--update` : Forces an update of the package(s) even if they are already present in `[tool.uv.sources]`.
+* `--delete-extra` : Removes any package found in `[tool.uv.sources]` that is not declared in `[tool.uvault.sources]`.
+* `--keep-develop` : By default, packages in develop mode (`editable = true` or using `path`) are restored to their vaulted state during sync. Use this flag to keep them in develop mode.
+
+### `uvault add`
+
+Adds a new dependency intention directly into `[tool.uvault.sources]` without manual file editing.
+
+**Arguments:**
+* `<package>` : The name of the package to add.
+* `[url]` : (Optional) The VCS URL (e.g. `https://github.com/OCA/my-addon`). If omitted, `uvault` will attempt to guess it from PyPI metadata.
+
+**Options:**
+* `--branch <name>` : Target a specific branch.
+* `--tag <name>` : Target a specific tag.
+* `--pr <number>` : Target a pull/merge request number.
+* `--rev <hash>` : Target a specific commit hash or exact reference.
+* `--subdirectory <path>` : The subdirectory within the repository where the Python package is located.
+
+### `uvault develop`
+
+Switches a vaulted dependency into local editable mode for active development.
+
+**Arguments:**
+* `<package>` : The name of the package to develop locally (must be declared in `[tool.uvault.sources]`).
+* `<branch>` : The name of the branch to checkout or create.
+
+**Workflow Details:**
+1. Clones (using a fast partial blobless clone) or fetches the repository into your `.src/` directory.
+2. Creates and checks out the new branch (`git checkout -b <branch>`), or switches to it if it exists (`git checkout <branch>`).
+3. Sets up remotes, including `origin`, `vault`, and any other custom remotes defined in `~/.config/uvault/config.toml`.
+4. Modifies `[tool.uv.sources]` to use `{ path = "./.src/<package>", editable = true }`.
+
+::: uvault.cli

uvault-0.2.0/mkdocs.yml

@@ -0,0 +1,15 @@
+site_name: uvault documentation
+theme:
+  name: material
+  features:
+    - navigation.tabs
+    - navigation.sections
+
+plugins:
+  - search
+  - mkdocstrings
+
+nav:
+  - Quickstart: index.md
+  - Tutorials / How-To: how-to.md
+  - Reference: reference.md

uvault-0.2.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "uvault"
+version = "0.2.0"
+description = "Development and vaulting workflow for uv VCS dependencies."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "diskcache>=5.6.3",
+    "tomlkit>=0.15.0",
+]
+
+[dependency-groups]
+dev = [
+    "bump-my-version>=1.3.0",
+    "mkdocs-material>=9.7.6",
+    "mkdocstrings[python]>=1.0.4",
+    "pre-commit>=4.6.0",
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.16",
+]
+
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project.scripts]
+uvault = "uvault.cli:main"
+
+[tool.pytest.ini_options]
+addopts = ["--cov=src/uvault", "--cov-report=term-missing", "--cov-fail-under=100"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.bumpversion]
+current_version = "0.2.0"
+commit = true
+tag = true
+tag_name = "v{new_version}"
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'
+
+[[tool.bumpversion.files]]
+filename = "src/uvault/__init__.py"
+search = '__version__ = "{current_version}"'
+replace = '__version__ = "{new_version}"'

uvault-0.2.0/src/uvault/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

uvault-0.2.0/src/uvault/add.py

@@ -0,0 +1,108 @@
+from pathlib import Path
+import urllib.parse
+import tomlkit
+
+from uvault.vcs import guess_repository_url
+
+
+class AddCommand:
+    def __init__(
+        self,
+        package: str,
+        url: str | None = None,
+        pr: str | None = None,
+        branch: str | None = None,
+        tag: str | None = None,
+        rev: str | None = None,
+        subdirectory: str | None = None,
+        pyproject_path: str = "pyproject.toml",
+    ):
+        self.package = package
+        self.url = url
+        self.pr = pr
+        self.branch = branch
+        self.tag = tag
+        self.rev = rev
+        self.subdirectory = subdirectory
+        self.pyproject_path = Path(pyproject_path)
+
+    def _parse_url(self):
+        if not self.url:
+            return
+
+        # Handle git+https://... format
+        if self.url.startswith("git+"):
+            url_no_git = self.url[4:]
+            parsed = urllib.parse.urlparse(url_no_git)
+
+            # Extract rev/branch/tag from @...
+            if "@" in parsed.path:
+                path, ref = parsed.path.split("@", 1)
+                self.url = f"{parsed.scheme}://{parsed.netloc}{path}"
+                self.rev = (
+                    ref  # by default it's a rev, could be branch/tag but uv accepts rev
+                )
+            else:
+                self.url = f"{parsed.scheme}://{parsed.netloc}{parsed.path}"
+
+            # Extract subdirectory from #subdirectory=...
+            if parsed.fragment:
+                fragments = urllib.parse.parse_qs(parsed.fragment)
+                if "subdirectory" in fragments:
+                    self.subdirectory = fragments["subdirectory"][0]
+
+    def run(self):
+        if not self.pyproject_path.exists():
+            print("pyproject.toml not found")
+            return 1
+
+        self._parse_url()
+
+        if not self.url:
+            guessed_url = guess_repository_url(self.package)
+            if not guessed_url:
+                print(f"Could not find or guess repository URL for {self.package}")
+                return 1
+            self.url = guessed_url
+            print(f"Guessed repository URL: {self.url}")
+
+        with open(self.pyproject_path, "r", encoding="utf-8") as f:
+            doc = tomlkit.parse(f.read())
+
+        if "tool" not in doc:
+            doc.add("tool", tomlkit.table())
+        if "uvault" not in doc["tool"]:
+            doc["tool"].add("uvault", tomlkit.table())
+        if "sources" not in doc["tool"]["uvault"]:
+            doc["tool"]["uvault"].add("sources", tomlkit.table())
+
+        uvault_sources = doc["tool"]["uvault"]["sources"]
+
+        new_source = tomlkit.inline_table()
+        new_source["git"] = self.url
+
+        # Priority: pr, rev, branch, tag
+        if self.pr:
+            if "github.com" in self.url:
+                new_source["rev"] = f"refs/pull/{self.pr}/head"
+            else:
+                new_source["rev"] = f"refs/merge-requests/{self.pr}/head"
+        elif self.rev:
+            new_source["rev"] = self.rev
+        elif self.branch:
+            new_source["branch"] = self.branch
+        elif self.tag:
+            new_source["tag"] = self.tag
+
+        if self.subdirectory:
+            new_source["subdirectory"] = self.subdirectory
+
+        uvault_sources[self.package] = new_source
+
+        with open(self.pyproject_path, "w", encoding="utf-8") as f:
+            f.write(tomlkit.dumps(doc))
+
+        print(f"Added {self.package} to [tool.uvault.sources]")
+        print("Run `uvault sync` to lock this dependency in [tool.uv.sources]")
+
+        return 0

uvault-0.2.0/src/uvault/cli.py

@@ -0,0 +1,87 @@
+import argparse
+import sys
+from uvault.sync import SyncCommand
+from uvault.develop import DevelopCommand
+from uvault.add import AddCommand
+
+
+def main(argv=None):
+    if argv is None:
+        argv = sys.argv[1:]  # pragma: no cover
+
+    parser = argparse.ArgumentParser(
+        description="Development and vaulting workflow for uv VCS dependencies."
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # Sync command
+    sync_parser = subparsers.add_parser("sync", help="Sync and vault VCS dependencies.")
+    sync_parser.add_argument(
+        "-U",
+        "--update",
+        action="store_true",
+        help="Force update the vaulted reference.",
+    )
+    sync_parser.add_argument(
+        "-P",
+        "--package",
+        action="append",
+        help="Specific package to sync. Can be used multiple times.",
+    )
+
+    sync_parser.add_argument(
+        "--delete-extra",
+        action="store_true",
+        help="Delete references in uv.sources that are not in uvault.sources.",
+    )
+    sync_parser.add_argument(
+        "--keep-develop",
+        action="store_true",
+        help="Keep packages that are in local develop mode instead of restoring them.",
+    )
+
+    # Add command
+    add_parser = subparsers.add_parser("add", help="Add a new vaulting intention.")
+    add_parser.add_argument("package", help="The package to add")
+    add_parser.add_argument("url", nargs="?", help="The VCS URL or PEP 508 string")
+    add_parser.add_argument("--pr", help="Pull request number")
+    add_parser.add_argument("--branch", help="Branch name")
+    add_parser.add_argument("--tag", help="Tag name")
+    add_parser.add_argument("--rev", help="Revision SHA")
+    add_parser.add_argument("--subdirectory", help="Subdirectory in the repository")
+
+    # Develop command
+    dev_parser = subparsers.add_parser("develop", help="Develop a package locally.")
+    dev_parser.add_argument("package", help="The package to develop")
+    dev_parser.add_argument("branch", help="Branch name to checkout or create")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "sync":
+        cmd = SyncCommand(
+            packages=args.package,
+            update=args.update,
+            delete_extra=args.delete_extra,
+            keep_develop=args.keep_develop,
+        )
+        return cmd.run()
+    elif args.command == "develop":
+        cmd = DevelopCommand(package=args.package, branch=args.branch)
+        return cmd.run()
+    elif args.command == "add":
+        cmd = AddCommand(
+            package=args.package,
+            url=args.url,
+            pr=args.pr,
+            branch=args.branch,
+            tag=args.tag,
+            rev=args.rev,
+            subdirectory=args.subdirectory,
+        )
+        return cmd.run()
+
+    return 0  # pragma: no cover
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())