GTO (Git Tag Ops)

Warnings

• breaking GTO dropped support for Python 3.8 in version 1.7.0. Users running GTO on Python 3.8 or older versions will encounter installation or runtime errors and must upgrade their Python environment to 3.9 or newer.
  Fix: Upgrade your Python interpreter to version 3.9 or higher. Review Python's official documentation for migration guidance if moving from significantly older versions.
• breaking GTO migrated to Pydantic V2 in version 1.9.0. This introduces significant breaking changes from Pydantic V1, affecting how models are defined, validated, and serialized. If your project has other dependencies pinning Pydantic V1 or directly uses Pydantic V1 APIs, this update will likely cause conflicts or runtime errors.
  Fix: Upgrade all Pydantic-dependent code and libraries to Pydantic V2. Utilize `bump-pydantic` tool for automated code migration. If a full migration is not immediately feasible, Pydantic V2 offers a compatibility layer to import V1 features via `from pydantic.v1 import BaseModel`.
• breaking GTO updated its internal `scmrepo` dependency to version 3.x in GTO 1.7.0. Major version bumps in `scmrepo` (a library for SCM operations) typically involve breaking API changes. While direct interaction with `scmrepo` might be abstracted by GTO, users who rely on internal `scmrepo` structures or have other `scmrepo`-dependent libraries might face compatibility issues.
  Fix: Ensure that if your project directly or indirectly depends on `scmrepo`, it is compatible with `scmrepo` version 3.x. Review `scmrepo`'s changelog for specific breaking changes in its 3.x release.
• gotcha GTO uses Git tags to store artifact versions and stage assignments. While `gto` commands create these tags locally, they are not automatically pushed to your remote Git repository. Failing to `git push --tags` means your artifact registry changes are not synchronized or visible to collaborators/CI/CD systems.
  Fix: Always remember to run `git push origin --tags` after performing `gto register` or `gto assign` (or any other `gto` command that creates/modifies tags) to ensure your registry state is shared and persistent.

Install

• pip install gto Install GTO

Imports

• gto

  import gto

  Primary import for accessing GTO's CLI and API functionality.
• gto.api

  from gto import api

  For direct programmatic access to GTO's operations like register, show, assign, etc.

Quickstart

This quickstart demonstrates how to use the `gto.api` to register an artifact and assign it to a stage within a Git repository. It simulates a basic Git workflow, registers 'my-model' from a 'model.pkl' file, and then promotes it to a 'dev' stage, finally showing the registry's state. Note that in a real scenario, `git push --tags` would be necessary to synchronize the GTO-managed tags with a remote repository.

import os
from pathlib import Path
import tempfile
import shutil
from gto import api

# Create a temporary directory for a mock Git repo
original_cwd = os.getcwd()
temp_dir = Path(tempfile.mkdtemp())
os.chdir(temp_dir)

try:
    # Initialize a Git repository
    os.system('git init -b main')
    os.system('git config user.email "test@example.com"')
    os.system('git config user.name "Test User"')
    
    # Create a dummy artifact file
    (temp_dir / "model.pkl").write_text("dummy_model_content")
    os.system('git add .')
    os.system('git commit -m "Initial commit with model.pkl"')

    # Register a new version of an artifact
    print("\n--- Registering artifact 'my-model' ---")
    api.register("my-model", "model.pkl", type="model", description="My first model")
    print("Artifact registered successfully.\n")

    # Show the current state of the artifact registry
    print("\n--- Showing artifact registry state ---")
    registry_state = api.show(name="my-model", json=True)
    print(registry_state)

    # Promote the artifact to a 'dev' stage
    print("\n--- Promoting 'my-model' to 'dev' stage ---")
    api.assign("my-model", stage="dev", version="my-model@v0.0.1")
    print("Artifact promoted to 'dev' stage successfully.\n")

    # Show the updated state
    print("\n--- Showing updated registry state ---")
    updated_registry_state = api.show(name="my-model", json=True)
    print(updated_registry_state)

    # Important: Push the Git tags for changes to be reflected remotely
    # In a real scenario: os.system('git push origin --tags')

finally:
    os.chdir(original_cwd)
    shutil.rmtree(temp_dir)