boxsdk.util package


boxsdk.util.api_call_decorator module

class boxsdk.util.api_call_decorator.APICallWrapper(func_that_makes_an_api_call)[source]

Bases: object


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

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.


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

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


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.

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

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


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.

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

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


register(type_name, box_cls)[source]

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

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

  • 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

The translated object

Module contents