ORAS Python SDK

Warnings

• breaking AWS ECR authentication support (`oras[ecr]`) was moved to an optional extra. If you were previously relying on ECR authentication without explicitly installing `oras[ecr]`, your setup will break.
  Fix: Ensure you install the `ecr` extra: `pip install oras[ecr]`.
• breaking Python 3.7+ compatibility was fixed, specifically regarding the use of union syntax (e.g., `list | None`). If you are using Python 3.7 or older, or if your environment relied on previous (potentially broken) behavior, this might affect you.
  Fix: Upgrade to `oras>=0.2.39` or ensure your Python environment is 3.8+ if you encounter syntax errors related to type hints.
• gotcha The authentication priority for various credential sources (AWS-native, docker login, credHelpers, credsStore) has been explicitly fixed and re-ordered. If your environment relies on a specific order of credential resolution, this change might alter how your client authenticates.
  Fix: Review your authentication setup and test with `oras>=0.2.36` to ensure credentials are resolved as expected. Debug authentication issues using the client's debug logs.
• gotcha There have been multiple fixes related to how Docker's `credsStore` and `credHelpers` binaries are located and used for authentication. Users relying on these Docker credential helpers might experience intermittent authentication failures or incorrect credential resolution.
  Fix: Ensure you are on the latest `oras` version to benefit from `credsStore`/`credHelpers` bug fixes. Verify your Docker configuration (`~/.docker/config.json`) and the availability of helper binaries.
• gotcha An open issue indicates potential data loss where `oras-py` strips paths to basename during pull operations, leading to filename collisions if multiple artifacts share the same basename. This could result in one artifact overwriting another upon pulling.
  Fix: When pulling, consider using unique output directories or carefully inspect the pulled files if you suspect filename collisions. Monitor the GitHub issues for a resolution.

Install

• pip install oras Base Installation
• pip install oras[ecr] With AWS ECR Authentication

Imports

• OrasClient

  from oras.client import OrasClient

  The primary client for interacting with OCI registries.
• ManifestConfig

  from oras.oci import ManifestConfig

  Used for creating OCI manifest configuration objects.

Quickstart

This quickstart demonstrates how to initialize an `OrasClient`, log in (if necessary), and then push and pull a simple artifact to/from an OCI-compliant registry. It uses environment variables for registry hostname, username, and password for flexibility, falling back to a local insecure registry setup for ease of testing.

import os
from oras.client import OrasClient

# Prepare a dummy file to push
with open('artifact.txt', 'w') as f:
    f.write('Hello, ORAS!')

registry_hostname = os.environ.get('ORAS_REGISTRY_HOSTNAME', 'localhost:5000')
repository_target = f"{registry_hostname}/my/artifact:v1"
username = os.environ.get('ORAS_USERNAME', '')
password = os.environ.get('ORAS_PASSWORD', '')

client = OrasClient(hostname=registry_hostname, insecure=True) # Use insecure=True for local registries without TLS

if username and password:
    print(f"Attempting to login to {registry_hostname}...")
    try:
        client.login(username=username, password=password)
        print("Login successful.")
    except Exception as e:
        print(f"Login failed: {e}")
        # Depending on local setup, login might not be strictly necessary for insecure local registries

print(f"Pushing artifact to {repository_target}...")
try:
    push_response = client.push(files=["artifact.txt"], target=repository_target)
    print(f"Push successful: {push_response}")
except Exception as e:
    print(f"Push failed: {e}")
    print("Ensure a registry is running at and accessible from '" + registry_hostname + "'. For example: 'docker run -d -p 5000:5000 --name oras-quickstart ghcr.io/oras-project/registry:latest'")

# Clean up after push if successful
# os.remove('artifact.txt') # Uncomment to clean up

# For pulling, create a new directory to avoid conflicts if artifact.txt already exists
pull_dir = './pulled_artifacts'
os.makedirs(pull_dir, exist_ok=True)

print(f"Pulling artifact from {repository_target} into {pull_dir}...")
try:
    # Pulls into the current working directory by default, unless oras.utils.workdir is used
    # For this example, we'll let it pull to current dir and specify path for clarity
    pulled_files = client.pull(target=repository_target, output_dir=pull_dir)
    print(f"Pull successful. Files: {pulled_files}")
    # Verify content if needed
    # with open(os.path.join(pull_dir, 'artifact.txt'), 'r') as f:
    #     print(f.read())
except Exception as e:
    print(f"Pull failed: {e}")

# Cleanup pulled files
# import shutil
# shutil.rmtree(pull_dir)
# os.remove('artifact.txt') # If not removed after push