boxsdk.util package¶

Submodules¶

boxsdk.util.api_call_decorator module¶

class boxsdk.util.api_call_decorator.APICallWrapper(func_that_makes_an_api_call)[source]¶: Bases: object

boxsdk.util.api_call_decorator.api_call(method)[source]¶

Designates the decorated method as one that makes a Box API call. The decorated method can then accept a new keyword argument extra_network_parameters, a dictionary of key-value pairs to be passed to the network layer for API calls made by the method.

The decorated method must belong to a subclass of Cloneable as using this decorator and then passing a extra_network_parameters parameter to the method will cause the object’s clone method to be called.

Parameters:	method (callable) – The method to decorate.
Returns:	A wrapped method that can pass extra request data to the network layer.
Return type:	`APICallWrapper`

boxsdk.util.chain_map module¶

class boxsdk.util.chain_map.ChainMap(*maps)[source]¶

Bases: chainmap.chainmap.ChainMap, object

A ChainMap groups multiple dicts (or other mappings) together to create a single, updateable view.

The underlying mappings are stored in a list. That list is public and can accessed or updated using the maps attribute. There is no other state.

Lookups search the underlying mappings successively until a key is found. In contrast, writes, updates, and deletions only operate on the first mapping.

boxsdk.util.compat module¶

boxsdk.util.compat.with_metaclass(meta, *bases, **with_metaclass_kwargs)[source]¶

Extends the behavior of six.with_metaclass.

The normal usage (expanded to include temporaries, to make the illustration easier) is:

temporary_class = six.with_metaclass(meta, *bases)
temporary_metaclass = type(temporary_class)

class Subclass(temporary_class):
    ...

SubclassMeta = type(Subclass)

In this example:

temporary_class is a class with (object,) as its bases.
temporary_metaclass is a metaclass with (meta,) as its bases.
Subclass is a class with bases as its bases.
SubclassMeta is meta.

six.with_metaclass() is defined in such a way that it can make sure that Subclass has the correct metaclass and bases, while only using syntax which is common to both Python 2 and Python 3. temporary_metaclass() returns an instance of meta, rather than an instance of itself / a subclass of temporary_class, which is how SubclassMeta ends up being meta, and how the temporaries don’t appear anywhere in the final subclass.

There are two problems with the current (as of six==1.10.0) implementation of six.with_metaclass(), which this function solves.

six.with_metaclass() does not define __prepare__() on the temporary metaclass. This means that meta.__prepare__() gets called directly, with bases set to (object,). If it needed to actually receive bases, then errors might occur. For example, this was a problem when used with enum.EnumMeta in Python 3.6. Here we make sure that __prepare__() is defined on the temporary metaclass, and pass bases to meta.__prepare__(). This is fixed in six>=1.11.0 by PR #178 [1].

Since temporary_class doesn’t have the correct bases, in theory this could cause other problems, besides the previous one, in certain edge cases. To make sure that doesn’t become a problem, we make sure that temporary_class has bases as its bases, just like the final class.

[1] <https://github.com/benjaminp/six/pull/178>

boxsdk.util.enum module¶

class boxsdk.util.enum.ExtendableEnumMeta[source]¶

Bases: enum.EnumMeta

A metaclass for enum hierarchies.

This allows you to define hierarchies such as this:

from box.util.compat import with_metaclass

class EnumBase(with_metaclass(ExtendableEnumMeta, Enum)): pass

class Enum1(EnumBase):

A = ‘A’

class Enum2(EnumBase): pass

class Enum2_1(Enum2):

B = ‘B’

class Enum2_2(Enum2):

C = ‘C’

and have all members be accessible on EnumBase (as well as have all members of Enum2_1 and Enum2_2 be available on Enum2) as if they had been defined there.

Non-leaf classes still may not have members directly defined on them, as with standard enums.

Most of the usual enum magic methods are extended: __contains__, __dir__, __getitem__, __getattr__, __iter__, __len__, and __reversed__. Only __new__ is not extended; instead, a new method lookup is provided. The __members__ property is also extended.

lookup(value)[source]¶

Custom value lookup, which does recursive lookups on subclasses.

If this is a leaf enum class with defined members, this acts the same as __new__().

But if this is a base class with no defined members of its own, it tries doing a value lookup on all its subclasses until it finds the value.

NOTE: Because of the implementation details of Enum, this must be a new classmethod, and can’t be implemented as __new__() [1].

[1] <https://docs.python.org/3.5/library/enum.html#finer-points>

Parameters:	value (varies) – The value to look up. Can be a value, or an enum instance.
Raises:	`ValueError` if the value isn’t found anywhere.

boxsdk.util.json module¶

boxsdk.util.json.is_json_response(network_response)[source]¶

Return whether or not the network response content is json.

Parameters:	network_response (`NetworkResponse`) – The response from the Box API.

boxsdk.util.log module¶

boxsdk.util.log.setup_logging(stream_or_file=<object object>, debug=False, name=None)[source]¶

Create a logger for communicating with the user or writing to log files. Sets the level to INFO or DEBUG, depending on the debug flag.

If a stream or file is passed (or None is passed to stream_or_file), then a handler to that stream or file (stdout for None) is added to the logger.

Parameters:	stream_or_file (unicode or file or None) – The destination of the log messages. If None, stdout will be used. debug (bool or None) – Whether or not the logger will be at the DEBUG level (if False, the logger will be at the INFO level). name (unicode or None) – The logging channel. If None, a root logger will be created.

boxsdk.util.log.sanitize_dictionary(dictionary)[source]¶

Get a copy of a dictionary that has sensitive information redacted. Should be called on objects that will be logged or printed.

Parameters:	dictionary (`Mapping`) – Dictionary that may contain sensitive information.
Returns:	Copy of the dictionary with sensitive information redacted.
Return type:	dict

boxsdk.util.lru_cache module¶

class boxsdk.util.lru_cache.LRUCache(capacity=512)[source]¶

Bases: object

get(key)[source]¶

Look up the value in cache using the associated key. Returns the value if found. Raises KeyError otherwise.

Parameters:	key (unicode) – The key used to look up the cache.
Returns:	The value associated with the key if exists.
Raises:	`KeyError` if the key doesn’t exist.

set(key, value=None)[source]¶

Store the key-value pair to cache.

Parameters:	key (unicode) – The key associated with the value to be stored. It’s used to look up the cache. value (varies) – The value to be stored.

boxsdk.util.multipart_stream module¶

class boxsdk.util.multipart_stream.MultipartStream(data, files)[source]¶

Bases: requests_toolbelt.multipart.encoder.MultipartEncoder

Subclass of the requests_toolbelt’s MultipartEncoder that ensures that data is encoded before files. This allows a server to process information in the data before receiving the file bytes.

boxsdk.util.shared_link module¶

boxsdk.util.shared_link.get_shared_link_header(shared_link, password=None)[source]¶

Gets the HTTP header required to use a shared link to grant access to a shared item.

Parameters:	shared_link (unicode) – The shared link. password (unicode) – The password for the shared link.
Returns:	The item referred to by the shared link.
Return type:	`Item`

boxsdk.util.text_enum module¶

class boxsdk.util.text_enum.TextEnum[source]¶: Bases: unicode, enum.Enum

boxsdk.util.translator module¶

class boxsdk.util.translator.Translator(*translation_maps, **kwargs)[source]¶

Bases: chainmap.chainmap.ChainMap

Translate item responses from the Box API to Box objects.

Also acts as a Mapping from type names to Box object classes.

There exists a global default Translator, containing the default API object classes defined by the SDK. Custom Translator instances can be created to extend the default Translator with custom subclasses.

A Translator is a ChainMap, so that one translator can “extend” others. The most common scenario would be a custom, non-global Translator that extends only the default translator, to register 0 or more new classes. But more complex inheritance is also allowed, in case that is useful.

get(key, default=None)[source]¶

Get the box object class associated with the given type name.

Parameters:	key (unicode) – The type name to be translated. default (`BaseAPIJSONObjectMeta`) – (optional) The default Box object class to return. Defaults to BaseObject.
Return type:	`BaseAPIJSONObjectMeta`

register(type_name, box_cls)[source]¶

Associate a Box object class to handle Box API item responses with the given type name.

Parameters:	type_name (unicode) – The type name to be registered. box_cls (`BaseAPIJSONObjectMeta`) – The Box object class, which will be associated with the type name provided.

translate(session, response_object)[source]¶

Translate a given API response object into SDK classes, rescursively translating any subobjects.

Parameters:	session (class:Session) – The SDK session to use for any objects that require a session (i.e. classes that make API calls) response_object (dict) – The JSON response object from the API, which will be translated
Returns:	The translated object