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_pull()
    • test_directory_push_pull()
    • test_get_delete_tags()
    • test_get_many_tags()
    • test_login_logout()
  • oras.tests.test_provider module
    • test_annotated_registry_push()
    • 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

class oras.auth. authHeader ( lookup : dict )

Bases: object

oras.auth. get_basic_auth ( username : str , password : str )

Prepare basic auth from a username and password.

Parameters :

• username ( str ) – the user account name

• password ( str ) – the user account password

oras.auth. load_configs ( configs : List [ str ] | None = None )

Load one or more configs with credentials from the filesystem.

Parameters :

configs ( optional list ) – list of configuration paths to load, defaults to None

oras.auth. parse_auth_header ( authHeaderRaw : str ) → authHeader

Parse authentication header into pieces

Parameters :

• username ( str ) – the user account name

• password ( str ) – the user account password

oras.client module

class oras.client. OrasClient ( hostname : str | None = None , registry : Registry | None = None , insecure : bool = False , tls_verify : bool = True )

Bases: object

Create an OCI Registry as Storage (ORAS) Client.

This is intended for controlled interactions. The user of oras-py can use this client, the terminal command line wrappers, or the functions in main in isolation as an internal Python API. The user can provide a custom registry as a parameter, if desired. If not provided we default to standard oras.

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

get_tags ( name : str , N = None ) → List [ str ]

Retrieve tags for a package.

Parameters :

• name ( str ) – container URI to parse

• N ( int ) – number of tags (None to get all tags)

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

Login to a registry.

Parameters :

• registry ( oras.provider.Registry or None ) – if provided, use this custom provider instead of default

• 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 ( list ) – list of config paths to add

logout ( hostname : str )

Logout from a registry, meaning removing any auth (if loaded)

Parameters :

hostname ( str ) – the hostname to login to

pull ( * args , ** kwargs )

Pull a container from the remote.

push ( * args , ** kwargs )

Push a container to the remote.

set_basic_auth ( username : str , password : str )

Add basic authentication to the request.

Parameters :

• username ( str ) – the user account name

• password ( str ) – the user account password

set_token_auth ( token : str )

Set token authentication.

Parameters :

token ( str ) – the bearer token

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.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

class oras.decorator. Decorator ( func )

Bases: object

Shared parent decorator class

class oras.decorator. classretry ( func , attempts = 5 , timeout = 2 )

Bases: Decorator

Retry a function that is part of a class

class oras.decorator. ensure_container ( func )

Bases: Decorator

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

oras.decorator. retry ( attempts , 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.

oras.provider module

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

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.

authenticate_request ( originalResponse : Response ) → bool

Authenticate Request Given a response, look for a Www-Authenticate header to parse.

We return True/False to indicate if the request should be retried.

Parameters :

originalResponse ( requests.Response ) – original response to get the Www-Authenticate header

chunked_upload ( blob : str , container : Container , layer : dict , refresh_headers : bool = True ) → 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

• refresh_headers ( bool ) – if true, headers are refreshed

delete_tag ( ** kwargs )

do_request ( ** kwargs )

download_blob ( ** kwargs )

get_blob ( ** kwargs )

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 ( ** kwargs )

get_tags ( ** kwargs )

load_configs ( ** kwargs )

logout ( hostname : str )

If auths are loaded, remove a hostname.

Parameters :

hostname ( str ) – the registry hostname to remove

pull ( * args , ** kwargs ) → 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

• refresh_headers ( bool ) – if true, headers are refreshed when fetching manifests

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

• outdir ( str ) – output directory path

• target ( str ) – target location to pull from

push ( * args , ** kwargs ) → 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

• refresh_headers ( bool ) – if true or None, headers are refreshed

• subject ( Subject ) – optional subject reference

put_upload ( blob : str , container : Container , layer : dict , refresh_headers : bool = True ) → 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

• refresh_headers ( bool ) – if true, headers are refreshed

request_anonymous_token ( h : authHeader ) → bool

Given no basic auth, fall back to trying to request an anonymous token.

Returns: boolean if headers have been updated with token.

reset_basic_auth ( )

Given we have basic auth, reset it.

set_basic_auth ( username : str , password : str )

Set basic authentication.

Parameters :

• username ( str ) – the user account name

• password ( str ) – the user account password

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

set_token_auth ( token : str )

Set token authentication.

Parameters :

token ( str ) – the bearer token

upload_blob ( blob : str , container : str | Container , layer : dict , do_chunked : bool = False , refresh_headers : bool = True ) → Response

Prepare and upload a blob.

Sizes > 1024 are uploaded via a chunked approach (post, patch+, put) and <= 1024 is a single post then 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

• refresh_headers ( bool ) – if true, headers are refreshed

upload_manifest ( manifest : dict , container : Container , refresh_headers : bool = True ) → Response

Read a manifest file and upload it.

Parameters :

• manifest ( dict ) – manifest to upload

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

• refresh_headers ( bool ) – if true, headers are refreshed

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

Bases: object

digest : str

mediaType : str

size : int

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

oras.schemas module

oras.version module

Module contents