wand.resource — Global resource management

There is the global resource to manage in MagickWand API. This module implements automatic global resource management through reference counting.

wand.resource.genesis()

Instantiates the MagickWand API.

Warning

Don’t call this function directly. Use increment_refcount() and decrement_refcount() functions instead.

wand.resource.terminus()

Cleans up the MagickWand API.

Warning

Don’t call this function directly. Use increment_refcount() and decrement_refcount() functions instead.

wand.resource.increment_refcount()

Increments the reference_count and instantiates the MagickWand API if it is the first use.

wand.resource.decrement_refcount()

Decrements the reference_count and cleans up the MagickWand API if it will be no more used.

wand.resource.limits = <wand.resource.ResourceLimits object>

(ResourceLimits) Helper to get & set Magick Resource Limits.

New in version 0.5.1.

class wand.resource.Resource

Abstract base class for MagickWand object that requires resource management. Its all subclasses manage the resource semiautomatically and support with statement as well:

with Resource() as resource:
    # use the resource...
    pass

It doesn’t implement constructor by itself, so subclasses should implement it. Every constructor should assign the pointer of its resource data into resource attribute inside of with allocate() context. For example:

class Pizza(Resource):
    '''My pizza yummy.'''

    def __init__(self):
        with self.allocate():
            self.resource = library.NewPizza()

New in version 0.1.2.

allocate()

Allocates the memory for the resource explicitly. Its subclasses should assign the created resource into resource attribute inside of this context. For example:

with resource.allocate():
    resource.resource = library.NewResource()
c_clear_exception = NotImplemented

(ctypes.CFUNCTYPE) The ctypes function that clears an exception of the resource.

Note

It is an abstract attribute that has to be implemented in the subclass.

c_destroy_resource = NotImplemented

(ctypes.CFUNCTYPE) The ctypes function that destroys the resource.

Note

It is an abstract attribute that has to be implemented in the subclass.

c_get_exception = NotImplemented

(ctypes.CFUNCTYPE) The ctypes function that gets an exception from the resource.

Note

It is an abstract attribute that has to be implemented in the subclass.

c_is_resource = NotImplemented

(ctypes.CFUNCTYPE) The ctypes predicate function that returns whether the given pointer (that contains a resource data usually) is a valid resource.

Note

It is an abstract attribute that has to be implemented in the subclass.

destroy()

Cleans up the resource explicitly. If you use the resource in with statement, it was called implicitly so have not to call it.

get_exception()

Gets a current exception instance.

Returns:a current exception. it can be None as well if any errors aren’t occurred
Return type:wand.exceptions.WandException
raise_exception(stacklevel=1)

Raises an exception or warning if it has occurred.

resource

Internal pointer to the resource instance. It may raise DestroyedResourceError when the resource has destroyed already.

class wand.resource.ResourceLimits

Wrapper for MagickCore resource limits. Useful for dynamically reducing system resources before attempting risky, or slow running, Image operations.

For example:

from wand.image import Image
from wand.resource import limits

# Use 100MB of ram before writing temp data to disk.
limits['memory'] = 1024 * 1024 * 100
# Reject images larger than 1000x1000.
limits['width'] = 1000
limits['height'] = 1000

# Debug resources used.
with Image(filename='user.jpg') as img:
    print('Using {0} of {1} memory'.format(limits.resource('memory'),
                                           limits['memory']))

# Dump list of all limits.
for label in limits:
    print('{0} => {1}'.format(label, limits[label]))

Available resource keys:

  • 'area' - Maximum width * height of a pixel cache before writing to disk.
  • 'disk' - Maximum bytes used by pixel cache on disk before exception is thrown.
  • 'file' - Maximum cache files opened at any given time.
  • 'height' - Maximum height of image before exception is thrown.
  • 'list_length' - Maximum images in sequence. Only available with recent version of ImageMagick.
  • 'map' - Maximum memory map in bytes to allocated for pixel cache before using disk.
  • 'memory' - Maximum bytes to allocated for pixel cache before using disk.
  • 'thread' - Maximum parallel task sub-routines can spawn - if using OpenMP.
  • 'throttle' - Total milliseconds to yield to CPU - if possible.
  • 'time' - Maximum seconds before exception is thrown.
  • 'width' - Maximum width of image before exception is thrown.

New in version 0.5.1.

get_resource_limit(resource)

Get the current limit for the resource type.

Parameters:resource (basestring) – Resource type.
Return type:numeric.Integral

New in version 0.5.1.

resource(resource)

Get the current value for the resource type.

Parameters:resource (basestring) – Resource type.
Return type:numeric.Integral

New in version 0.5.1.

set_resource_limit(resource, limit)

Sets a new limit for resource type.

Note

The new limit value must be equal to, or less then, the maximum limit defined by the policy.xml. Any values set outside normal bounds will be ignored silently.

Parameters:
  • resource (basestring) – Resource type.
  • limit (numeric.Integral) – New limit value.

New in version 0.5.1.

exception wand.resource.DestroyedResourceError

An error that rises when some code tries access to an already destroyed resource.

Changed in version 0.3.0: It becomes a subtype of wand.exceptions.WandException.

wand.resource.safe_copy(ptr)

Safely cast memory address to char pointer, convert to python string, and immediately free resources.

Parameters:ptr (ctypes.c_void_p) – The memory address to convert to text string.
Returns:tuple (ctypes.c_void_p, str)

New in version 0.5.3.