oras package

Subpackages

• oras.main package
  • Submodules
  • oras.main.login module
    • DockerClient
      • DockerClient.login()
  • Module contents
• oras.tests package
  • Submodules
  • oras.tests.test_oras module
    • test_basic_oras()
    • test_basic_push_pul_via_sha_ref()
    • test_basic_push_pull()
    • test_custom_docker_config_path()
    • test_directory_push_pull()
    • test_directory_push_pull_selfsigned_auth()
    • test_get_delete_tags()
    • test_get_many_tags()
    • test_login_logout()
  • oras.tests.test_provider module
    • test_annotated_registry_push()
    • test_chunked_push()
    • test_file_contains_column()
    • test_parse_manifest()
    • test_sanitize_path()
  • oras.tests.test_utils module
    • test_copyfile()
    • test_get_tmpdir_tmpfile()
    • test_mkdir_p()
    • test_print_json()
    • test_split_path_and_content()
    • test_workdir()
    • test_write_bad_json()
    • test_write_json()
    • test_write_read_files()
  • Module contents
• oras.utils package
  • Submodules
  • oras.utils.fileio module
    • PathAndOptionalContent
    • copyfile()
    • extract_targz()
    • get_file_hash()
    • get_size()
    • get_tmpdir()
    • get_tmpfile()
    • is_within_directory()
    • make_targz()
    • mkdir_p()
    • print_json()
    • read_file()
    • read_in_chunks()
    • read_json()
    • readline()
    • recursive_find()
    • sanitize_path()
    • split_path_and_content()
    • workdir()
    • write_file()
    • write_json()
  • oras.utils.request module
    • append_url_params()
    • find_docker_config()
    • get_docker_client()
    • iter_localhosts()
  • Module contents

Submodules

oras.auth module

exception oras.auth. AuthenticationException

Bases: Exception

An exception to raise when Authentication errors are fatal

oras.auth. get_auth_backend ( name = 'token' , session = None , insecure = False , ** kwargs )

oras.client module

oras.container module

class oras.container. Container ( name : str , registry : str | None = None )

Bases: object

property api_prefix

Return the repository prefix for the v2 API endpoints.

get_blob_url ( digest : str ) → str

Get the URL to download a blob

Parameters :

digest ( str ) – the digest to download

manifest_url ( tag : str | None = None ) → str

Get the manifest url for a specific tag, or the one for this container.

The tag provided can also correspond to a digest.

Parameters :

tag ( None or str ) – an optional tag to provide (if not provided defaults to container)

parse ( name : str )

Parse the container name into registry, repository, and tag.

Parameters :

name ( str ) – the full name of the container to parse (with any components)

tags_url ( N = None ) → str

upload_blob_url ( ) → str

property uri : str

Assemble the complete unique resource identifier

oras.decorator module

oras.decorator. ensure_container ( func )

Ensure the first argument is a container, and not a string.

oras.decorator. retry ( attempts = 5 , timeout = 2 )

A simple retry decorator

oras.defaults module

class oras.defaults. registry

Bases: object

default_v2_registry = {'host': 'registry-1.docker.io', 'scheme': 'https'}

index_hostname = 'index.docker.io'

index_name = 'docker.io'

index_server = 'https://index.docker.io/v1/'

oras.logger module

class oras.logger. ColorizingStreamHandler ( nocolor: bool = False , stream: str | ~pathlib.Path | ~typing.TextIO = <_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'> , use_threads: bool = False )

Bases: StreamHandler

BLACK = 0

BLUE = 4

BOLD_SEQ = '\x1b[1m'

COLOR_SEQ = '\x1b[%dm'

CYAN = 6

GREEN = 2

MAGENTA = 5

RED = 1

RESET_SEQ = '\x1b[0m'

WHITE = 7

YELLOW = 3

can_color_tty ( ) → bool

Determine if the tty supports color

colors = {'CRITICAL': 1, 'DEBUG': 4, 'ERROR': 1, 'INFO': 2, 'WARNING': 3}

decorate ( record ) → str

Decorate a log record

Parameters :

record – the record to emit

emit ( record : LogRecord )

Emit a log record

Parameters :

record ( logging.LogRecord ) – the record to emit

property is_tty : bool

Determine if we have a tty environment

class oras.logger. Logger

Bases: object

cleanup ( )

Close open files, etc. for the logger

debug ( msg : str )

Debug level message

Parameters :

msg ( str ) – the debug message

error ( msg : str )

Error level message

Parameters :

msg ( str ) – the error message

exit ( msg : str , return_code : int = 1 )

Error level message and exit with error code

Parameters :

• msg ( str ) – the exiting (error) message

• return_code ( int ) – return code to exit on

handler ( msg : dict )

Handle a log message.

Parameters :

msg ( dict ) – the message to handle

info ( msg : str )

Info level message

Parameters :

msg ( str ) – the informational message

location ( msg : str )

Debug level message with location info.

Parameters :

msg ( dict ) – the logging message

progress ( done : int , total : int )

Show piece of a progress bar

Parameters :

• done ( int ) – count of total that is complete

• total ( int ) – count of total

set_level ( level : int )

Set the logging level.

Parameters :

level ( int ) – the logging level to set

set_stream_handler ( stream_handler : Handler )

Set a stream handler.

:param stream_handler : the stream handler :type stream_handler: logging.Handler

shellcmd ( msg : str | None )

Shellcmd message

Parameters :

msg ( str ) – the message

text_handler ( msg : dict )

The default log handler that prints to the console.

Parameters :

msg ( dict ) – the log message dict

warning ( msg : str )

Warning level message

Parameters :

msg ( str ) – the warning message

oras.logger. setup_logger ( quiet : bool = False , printshellcmds : bool = False , nocolor : bool = False , stdout : bool = False , debug : bool = False , use_threads : bool = False )

Setup the logger. This should be called from an init or client.

Parameters :

• quiet ( bool ) – set logging level to quiet

• printshellcmds ( bool ) – a special level to print shell commands

• nocolor ( bool ) – do not use color

• stdout ( bool ) – print to standard output for the logger

• debug ( bool ) – debug level logging

• use_threads ( bool ) – use threads!

oras.oci module

class oras.oci. Annotations ( filename = None )

Bases: object

Create a new set of annotations

add ( section , key , value )

Add key/value pairs to a named section.

get_annotations ( section : str ) → dict

Given the name (a relative path or named section) get annotations

load ( filename : str )

class oras.oci. Layer ( blob_path : str , media_type : str | None = None , is_dir : bool = False )

Bases: object

set_media_type ( media_type : str | None = None , is_dir : bool = False )

Vary the media type to be directory or default layer

Parameters :

• media_type ( str ) – media type for the blob (optional)

• is_dir ( bool ) – is the blob a directory?

to_dict ( )

Return a dictionary representation of the layer

oras.oci. ManifestConfig ( path : str | None = None , media_type : str | None = None ) → Tuple [ Dict [ str , object ] , str | None ]

Write an empty config, if one is not provided

Parameters :

• path ( str ) – the path of the manifest config, if exists.

• media_type ( str ) – media type for the manifest config (optional)

oras.oci. NewLayer ( blob_path : str , media_type : str | None = None , is_dir : bool = False ) → dict

Courtesy function to create and retrieve a layer as dict

Parameters :

• blob_path ( str ) – the path of the blob for the layer

• media_type ( str ) – media type for the blob (optional)

• is_dir ( bool ) – is the blob a directory?

oras.oci. NewManifest ( ) → dict

Get an empty manifest config.

class oras.oci. Subject ( mediaType : str , digest : str , size : int )

Bases: object

digest : str

classmethod from_manifest ( manifest : dict ) → Subject

Create a new Subject from a Manifest

Parameters :

manifest – manifest to convert to subject

mediaType : str

size : int

oras.provider module

class oras.provider. Registry ( hostname : str | None = None , insecure : bool = False , tls_verify : bool = True , auth_backend : str = 'token' )

Bases: object

Direct interactions with an OCI registry.

This could also be called a “provider” when we add in the “copy” logic and the registry isn’t necessarily the “remote” endpoint.

blob_exists ( layer : Layer , container : Container ) → bool

Check if a layer already exists in the registry.

Parameters :

• layer ( oras.oci.Layer ) – the layer to check for existence

• container ( oras.container.Container ) – the container to determine where to look for layer existence

chunked_upload ( blob : str , container : Container , layer : dict , chunk_size : int = 16777216 ) → Response

Upload via a chunked upload.

Parameters :

• blob ( str ) – path to blob to upload

• container ( oras.container.Container or str ) – parsed container URI

• layer ( dict ) – dict from oras.oci.NewLayer

• chunk_size ( int ) – chunk size in bytes

delete_tag ( container : str | Container , tag : str ) → bool

Delete a tag for a container.

Parameters :

• container ( oras.container.Container or str ) – parsed container URI

• tag ( str ) – name of tag to delete

delete_tags ( name : str , tags = typing.Union[str, list] ) → List [ str ]

Delete one or more tags for a unique resource identifier.

Returns those successfully deleted.

Parameters :

• name ( str ) – container URI to parse

• tags – single or multiple tags name to delete

do_request ( url : str , method : str = 'GET' , data : dict | bytes | None = None , headers : dict | None = None , json : dict | None = None , stream : bool = False ) → Response

Do a request. This is a wrapper around requests to handle retry auth.

Parameters :

• url ( str ) – the URL to issue the request to

• method ( str ) – the method to use (GET, DELETE, POST, PUT, PATCH)

• data ( dict or bytes ) – data for requests

• headers ( dict ) – headers for the request

• json ( dict ) – json data for requests

• stream ( bool ) – stream the responses

download_blob ( container : str | Container , digest : str , outfile : str ) → str

Stream download a blob into an output file.

This function is a wrapper around get_blob.

Parameters :

container ( oras.container.Container or str ) – parsed container URI

get_blob ( container : str | Container , digest : str , stream : bool = False , head : bool = False ) → Response

Retrieve a blob for a package.

Parameters :

• container ( oras.container.Container or str ) – parsed container URI

• digest ( str ) – sha256 digest of the blob to retrieve

• stream ( bool ) – stream the response (or not)

• head ( bool ) – use head to determine if blob exists

get_container ( name : str | Container ) → Container

Courtesy function to get a container from a URI.

Parameters :

name ( oras.container.Container or str ) – unique resource identifier to parse

get_manifest ( container : str | Container , allowed_media_type : list | None = None ) → dict

Retrieve a manifest for a package.

Parameters :

• container ( oras.container.Container or str ) – parsed container URI

• allowed_media_type ( str ) – one or more allowed media types

get_tags ( container : str | Container , N = None ) → List [ str ]

Retrieve tags for a package.

Parameters :

• container ( oras.container.Container or str ) – parsed container URI

• N ( Optional [ int ] ) – limit number of tags, None for all (default)

login ( username : str , password : str , password_stdin : bool = False , tls_verify : bool = True , hostname : str | None = None , config_path : str | None = None ) → dict

Login to a registry.

Parameters :

• username ( str ) – the user account name

• password ( str ) – the user account password

• password_stdin ( bool ) – get the password from standard input

• insecure ( bool ) – use http instead of https

• tls_verify ( bool ) – verify tls

• hostname ( str ) – the hostname to login to

• config_path ( str ) – custom config path to add credentials to

logout ( hostname : str )

If auths are loaded, remove a hostname.

Parameters :

hostname ( str ) – the registry hostname to remove

pull ( target : str , config_path : str | None = None , allowed_media_type : List | None = None , overwrite : bool = True , outdir : str | None = None ) → List [ str ]

Pull an artifact from a target

Parameters :

• config_path ( str ) – path to a config file

• allowed_media_type ( list or None ) – list of allowed media types

• overwrite ( bool ) – if output file exists, overwrite

• manifest_config_ref ( str ) – save manifest config to this file

• outdir ( str ) – output directory path

• target ( str ) – target location to pull from

push ( target : str , config_path : str | None = None , disable_path_validation : bool = False , files : List | None = None , manifest_config : str | None = None , annotation_file : str | None = None , manifest_annotations : dict | None = None , subject : str | None = None , do_chunked : bool = False , chunk_size : int = 16777216 ) → Response

Push a set of files to a target

Parameters :

• config_path ( str ) – path to a config file

• disable_path_validation ( bool ) – ensure paths are relative to the running directory.

• files ( list ) – list of files to push

• insecure ( bool ) – allow registry to use http

• annotation_file ( str ) – manifest annotations file

• manifest_annotations ( dict ) – manifest annotations

• target ( str ) – target location to push to

• do_chunked ( bool ) – if true do chunked blob upload

• chunk_size ( int ) – chunk size in bytes

• subject ( oras.oci.Subject ) – optional subject reference

put_upload ( blob : str , container : Container , layer : dict ) → Response

Upload to a registry via put.

Parameters :

• blob ( str ) – path to blob to upload

• container ( oras.container.Container or str ) – parsed container URI

• layer ( dict ) – dict from oras.oci.NewLayer

set_header ( name : str , value : str )

Courtesy function to set a header

Parameters :

• name ( str ) – header name to set

• value ( str ) – header value to set

upload_blob ( blob : str , container : str | Container , layer : dict , do_chunked : bool = False , chunk_size : int = 16777216 ) → Response

Prepare and upload a blob.

Large artifacts can be uploaded via a chunked approach (post, patch+, put) to registries that support it. Larger chunks generally give better throughput. Set do_chunked=True for chunked upload.

Parameters :

• blob ( str ) – path to blob to upload

• container ( oras.container.Container or str ) – parsed container URI

• layer ( dict ) – dict from oras.oci.NewLayer

• do_chunked ( bool ) – if true do chunked blob upload. This allows upload of larger oci artifacts.

• chunk_size ( int ) – if true use chunked upload.

upload_manifest ( manifest : dict , container : Container ) → Response

Read a manifest file and upload it.

Parameters :

• manifest ( dict ) – manifest to upload

• container ( oras.container.Container or str ) – parsed container URI

version ( return_items : bool = False ) → dict | str

Get the version of the client.

:param return_items : return the dict of version info instead of string :type return_items: bool

oras.provider. temporary_empty_config ( ) → Generator [ str , None , None ]

oras.schemas module

oras.version module

Module contents