Vips.Source¶

Subclasses:: Vips.SourceCustom, Vips.SourceGInputStream

Methods¶

Inherited:: Vips.Connection (2), Vips.Object (27), GObject.Object (37)
Structs:: Vips.ObjectClass (1), GObject.ObjectClass (5)

class	`new_from_blob` (blob)
class	`new_from_descriptor` (descriptor)
class	`new_from_file` (filename)
class	`new_from_memory` (data, length)
class	`new_from_options` (options)
class	`new_from_target` (target)
	`decode` ()
	`is_file` ()
	`is_mappable` ()
	`length` ()
	`map` (length)
	`map_blob` ()
	`minimise` ()
	`read` (buffer, length)
	`rewind` ()
	`seek` (offset, whence)
	`sniff` (length)
	`sniff_at_most` (data, length)
	`unminimise` ()

Virtual Methods¶

Inherited:: Vips.Object (9), GObject.Object (7)

	`do_read` (buffer, length)
	`do_seek` (offset, whence)

Properties¶

Inherited:: Vips.Connection (2), Vips.Object (2)

Name	Type	Flags	Short Description
`blob`	`Vips.Blob`	r/w	Blob to load from

Signals¶

Inherited:: Vips.Object (4), GObject.Object (1)

Fields¶

Inherited:: Vips.Object (4), GObject.Object (1)

Name	Type	Access
blob	`Vips.Blob`	r
data	`object`	r
have_tested_seek	`bool`	r
header_bytes	`bytes`	r
is_pipe	`bool`	r
mmap_baseaddr	`object`	r
mmap_length	`int`	r
parent_object	`Vips.Connection`	r
read_position	`int`	r

Class Details¶

class Vips.Source(**kwargs)¶

Bases:: Vips.Connection
Abstract:: No
Structure:: Vips.SourceClass

A [class`Source`] provides a unified interface for reading, seeking, and mapping data, regardless of the underlying source type.

This source can originate from something like a socket, file or memory area.

During the header phase, we save data from unseekable sources in a buffer so readers can rewind and read again. We don’t buffer data during the decode stage.

classmethod new_from_blob(blob)¶

Parameters:: blob (Vips.Blob) – memory area to load
Returns:: a new source.
Return type:: Vips.Source

Create a source attached to an area of memory.

classmethod new_from_descriptor(descriptor)¶

Parameters:: descriptor (int) – read from this file descriptor
Returns:: a new source.
Return type:: Vips.Source

Create an source attached to a file descriptor. descriptor is closed with close()) when source is finalized.

classmethod new_from_file(filename)¶

Parameters:: filename (str) – read from this filename
Returns:: a new source.
Return type:: Vips.Source

Create a source attached to a file.

If this descriptor does not support mmap and the source is used with a loader that can only work from memory, then the data will be automatically read into memory to EOF before the loader starts. This can produce high memory use if the descriptor represents a large object.

Use [func`pipe_read_limit_set`] to limit the size of object that will be read in this way. The default is 1GB.

classmethod new_from_memory(data, length)¶

Parameters:

data (object or None) – memory area to load
length (int) – size of memory area

Returns:

a new source.

Return type:

Vips.Source

Create a source attached to an area of memory.

You must not free data while the source is active.

classmethod new_from_options(options)¶

Parameters:: options (str) – option string
Returns:: a new source.
Return type:: Vips.Source

Create a source from an option string.

classmethod new_from_target(target)¶

Parameters:: target (Vips.Target) – build the source from this target
Returns:: a new source.
Return type:: Vips.Source

Create a source from a temp target that has been written to.

decode()¶

Returns:: 0 on success, -1 on error.
Return type:: int

Signal the end of header read and the start of the pixel decode phase. After this, you can no longer seek on this source.

Loaders should call this at the end of header read.

::: seealso [method`Source`.unminimise].

is_file()¶

Returns:: TRUE if the source is a simple file.
Return type:: bool

Test if this source is a simple file with support for seek. Named pipes, for example, will fail this test. If TRUE, you can use [method`Connection`.filename] to find the filename.

Use this to add basic source support for older loaders which can only work on files.

is_mappable()¶

Returns:: TRUE if the source can be efficiently mapped into memory.
Return type:: bool

Some sources can be efficiently mapped into memory. You can still use [method`Source`.map] if this function returns FALSE, but it will be slow.

length()¶

Returns:: number of bytes in source, or -1 on error.
Return type:: int

Return the length in bytes of the source. Unseekable sources, for example pipes, will have to be read entirely into memory before the length can be found, so this operation can take a long time.

map(length)¶

Parameters:: length (int) – return the file length here, or NULL
Returns:: a pointer to the start of the file contents, or NULL on error.
Return type:: object or None

Map the source entirely into memory and return a pointer to the start. If length is non-None, the source size is written to it.

This operation can take a long time. Use [method`Source`.is_mappable] to check if a source can be mapped efficiently.

The pointer is valid for as long as self is alive.

map_blob()¶

Returns:: a new [struct`Blob`] containing the data, or NULL on error.
Return type:: Vips.Blob

Just like [method`Source`.map], but return a [struct`Blob`] containing the pointer. self will stay alive as long as the result is alive.

minimise()¶

Minimise the source. As many resources as can be safely removed are removed. Use [method`Source`.unminimise] to restore the source if you wish to use it again.

Loaders should call this in response to the minimise signal on their output image.

read(buffer, length)¶

Parameters:

buffer (object or None) – store bytes here
length (int) – length of buffer in bytes

Returns:

the number of bytes read, 0 on end of file, -1 on error.

Return type:

int

Read up to length bytes from self and store the bytes in buffer. Return the number of bytes actually read. If all bytes have been read from the file, return 0.

Arguments exactly as read()).

rewind()¶

Returns:: 0 on success, or -1 on error.
Return type:: int

Rewind the source to the start.

You can’t always do this after the pixel decode phase starts – for example, pipe-like sources can’t be rewound.

seek(offset, whence)¶

Parameters:

offset (int) – seek by this offset
whence (int) – seek relative to this point

Returns:

the new file position, or -1 on error.

Return type:

int

Move the file read position. You can’t call this after pixel decode starts. The arguments are exactly as lseek()).

sniff(length)¶

Parameters:: length (int) – number of bytes to sniff
Returns:: a pointer to the bytes at the start of the file, or NULL on error.
Return type:: int

Return a pointer to the first few bytes of the file. If the file is too short, return NULL.

sniff_at_most(data, length)¶

Parameters:

data (int) – return a pointer to the bytes read here
length (int) – max number of bytes to read

Returns:

number of bytes read, or -1 on error.

Return type:

int

Attempt to sniff at most length bytes from the start of the source. A pointer to the bytes is returned in data. The number of bytes actually read is returned – it may be less than length if the file is shorter than length. A negative number indicates a read error.

unminimise()¶

Returns:: 0 on success, or -1 on error.
Return type:: int

Restore the source after minimisation. This is called at the start of every source method, so loaders should not usually need this.

::: seealso [method`Source`.minimise].

do_read(buffer, length) virtual¶

Parameters:

buffer (object or None) – store bytes here
length (int) – length of buffer in bytes

Returns:

the number of bytes read, 0 on end of file, -1 on error.

Return type:

int

Read up to length bytes from source and store the bytes in buffer. Return the number of bytes actually read. If all bytes have been read from the file, return 0.

Arguments exactly as read()).

do_seek(offset, whence) virtual¶

Parameters:

offset (int) – seek by this offset
whence (int) – seek relative to this point

Returns:

the new file position, or -1 on error.

Return type:

int

Move the file read position. You can’t call this after pixel decode starts. The arguments are exactly as lseek()).

Property Details¶

Vips.Source.props.blob¶

Name:: blob
Type:: Vips.Blob
Default Value:: None
Flags:: READABLE, WRITABLE

Blob to load from