b2sdk.utils

b2sdk.utils.b2_url_encode(s)[source]

URL-encode a unicode string to be sent to B2 in an HTTP header.

Parameters:

s (str) – a unicode string to encode

Returns:

URL-encoded string

Return type:

str

b2sdk.utils.b2_url_decode(s)[source]

Decode a Unicode string returned from B2 in an HTTP header.

Parameters:

s (str) – a unicode string to decode

Returns:

a Python unicode string.

Return type:

str

b2sdk.utils.choose_part_ranges(content_length, minimum_part_size)[source]

Return a list of (offset, length) for the parts of a large file.

Parameters:
  • content_length (int) – content length value

  • minimum_part_size (int) – a minimum file part size

Return type:

list

b2sdk.utils.update_digest_from_stream(digest, input_stream, content_length)[source]

Update and return digest with data read from input_stream

Parameters:
  • digest (TypeVar(T)) – a digest object, which exposes an update(bytes) method

  • input_stream (Any) – stream object, which exposes a read(int|None) method

  • content_length (int) – expected length of the stream

Return type:

TypeVar(T)

b2sdk.utils.hex_sha1_of_stream(input_stream, content_length)[source]

Return the 40-character hex SHA1 checksum of the first content_length bytes in the input stream.

Parameters:
  • input_stream (Any) – stream object, which exposes read(int|None) method

  • content_length (int) – expected length of the stream

Return type:

str

class b2sdk.utils.IncrementalHexDigester(stream, digest=<factory>, read_bytes=0, block_size=1048576)[source]

Bases: object

Calculates digest of a stream or parts of it.

stream: ReadOnlyStream
digest: hashlib._Hash
read_bytes: int = 0
block_size: int = 1048576
property hex_digest: Sha1HexDigest
update_from_stream(limit=None)[source]
Parameters:

limit (Optional[int]) – How many new bytes try to read from the stream. Default None – read until nothing left.

Return type:

NewType(Sha1HexDigest, str)

__init__(stream, digest=<factory>, read_bytes=0, block_size=1048576)
b2sdk.utils.hex_sha1_of_unlimited_stream(input_stream, limit=None)[source]
Parameters:
Return type:

tuple[NewType(Sha1HexDigest, str), int]

b2sdk.utils.hex_sha1_of_file(path_)[source]
Return type:

NewType(Sha1HexDigest, str)

b2sdk.utils.hex_sha1_of_bytes(data)[source]

Return the 40-character hex SHA1 checksum of the data.

Parameters:

data (bytes) –

Return type:

NewType(Sha1HexDigest, str)

b2sdk.utils.hex_md5_of_bytes(data)[source]

Return the 32-character hex MD5 checksum of the data.

Parameters:

data (bytes) –

Return type:

str

b2sdk.utils.md5_of_bytes(data)[source]

Return the 16-byte MD5 checksum of the data.

Parameters:

data (bytes) –

Return type:

bytes

b2sdk.utils.b64_of_bytes(data)[source]

Return the base64 encoded represtantion of the data.

Parameters:

data (bytes) –

Return type:

str

b2sdk.utils.validate_b2_file_name(name)[source]

Raise a ValueError if the name is not a valid B2 file name.

Parameters:

name (str) – a string to check

b2sdk.utils.is_file_readable(local_path, reporter=None)[source]

Check if the local file has read permissions.

Parameters:
  • local_path (str) – a file path

  • reporter – reporter object to put errors on

Return type:

bool

b2sdk.utils.get_file_mtime(local_path)[source]

Get modification time of a file in milliseconds.

Parameters:

local_path (str) – a file path

Return type:

int

b2sdk.utils.is_special_file(path)[source]

Is the path a special file, such as /dev/null or stdout?

Parameters:

path (str | Path) – a “file” path

Return type:

bool

Returns:

True if the path is a special file

b2sdk.utils.set_file_mtime(local_path, mod_time_millis)[source]

Set modification time of a file in milliseconds.

Parameters:
  • local_path (str | Path) – a file path

  • mod_time_millis (int) – time to be set

Return type:

None

b2sdk.utils.fix_windows_path_limit(path)[source]

Prefix paths when running on Windows to overcome 260 character path length limit. See https://msdn.microsoft.com/en-us/library/windows/desktop/aa365247(v=vs.85).aspx#maxpath

Parameters:

path (str) – a path to prefix

Returns:

a prefixed path

Return type:

str

b2sdk.utils.format_and_scale_number(x, unit)[source]

Pick a good scale for representing a number and format it.

Parameters:
  • x (int) – a number

  • unit (str) – an arbitrary unit name

Returns:

scaled and formatted number

Return type:

str

b2sdk.utils.format_and_scale_fraction(numerator, denominator, unit)[source]

Pick a good scale for representing a fraction, and format it.

Parameters:
  • numerator (int) – a numerator of a fraction

  • denominator (int) – a denominator of a fraction

  • unit (str) – an arbitrary unit name

Returns:

scaled and formatted fraction

Return type:

str

b2sdk.utils.camelcase_to_underscore(input_)[source]

Convert a camel-cased string to a string with underscores.

Parameters:

input (str) – an input string

Returns:

string with underscores

Return type:

str

class b2sdk.utils.B2TraceMeta(name, bases, attrs, **kwargs)[source]

Bases: DefaultTraceMeta

Trace all public method calls, except for ones with names that begin with get_.

class b2sdk.utils.B2TraceMetaAbstract(name, bases, namespace, /, **kwargs)[source]

Bases: DefaultTraceAbstractMeta

Default class for tracers, to be set as a metaclass for abstract base classes.

class b2sdk.utils.ConcurrentUsedAuthTokenGuard(lock, token)[source]

Bases: object

Context manager preventing two tokens being used simultaneously. Throws UploadTokenUsedConcurrently when unable to acquire a lock Sample usage:

with ConcurrentUsedAuthTokenGuard(lock_for_token, token):

# code that uses the token exclusively

__init__(lock, token)[source]
b2sdk.utils.current_time_millis()[source]

File times are in integer milliseconds, to avoid roundoff errors.

b2sdk.utils.iterator_peek(iterator, count)[source]

Get up to the count first elements yielded by iterator.

The function will read count elements from iterator or less if the end is reached first. Returns a tuple consisting of a list of retrieved elements and an iterator equivalent to the input iterator.

Parameters:
Return type:

tuple[list[TypeVar(T)], Iterator[TypeVar(T)]]