exiv2._basicio
Classes to access files, memory and remote data.
Classes
An interface for simple binary IO. |
|
Provides binary file IO by implementing the BasicIo interface. |
|
Provides the http read/write access for the RemoteIo. |
|
Provides binary IO on blocks of memory by implementing the BasicIo interface. |
|
Provides remote binary file IO by implementing the BasicIo interface. |
|
Provides binary IO for the data from stdin and data uri path. |
- class BasicIo
Bases:
SwigPyObjectAn interface for simple binary IO.
Designed to have semantics and names similar to those of C style FILE* operations. Subclasses should all behave the same so that they can be interchanged.
- close()
Close the IO source. After closing a BasicIo instance can not be read or written. Closing flushes any unwritten data. It is safe to call close on a closed instance.
- Return type:
- Returns:
0 if successful;
Nonzero if failure.
- eof()
Returns true if the IO position has reached the end, otherwise false.
- error()
Returns 0 if the IO source is in a valid state, otherwise nonzero.
- getb()
Read one byte from the IO source. Current IO position is advanced by one byte.
- Return type:
- Returns:
The byte read from the IO source if successful;
EOF if failure;
- isopen()
Returns true if the IO source is open, otherwise false.
- mmap()
Direct access to the IO data. For files, this is done by mapping the file into the process’s address space; for memory blocks, this allows direct access to the memory block.
- Parameters:
isWriteable (bool, optional) – Set to true if the mapped area should be writeable (default is false).
- Return type:
- Returns:
A pointer to the mapped area.
- Raises:
Exiv2ErrorIn case of failure.
- munmap()
Remove a mapping established with mmap(). If the mapped area is writeable, this ensures that changes are written back.
- Return type:
- Returns:
0 if successful;
Nonzero if failure;
- open()
Open the IO source using the default access mode. The default mode should allow for reading and writing.
This method can also be used to “reopen” an IO source which will flush any unwritten data and reset the IO position to the start. Subclasses may provide custom methods to allow for opening IO sources differently.
- Return type:
- Returns:
0 if successful;
Nonzero if failure.
- path()
Return the path to the IO resource. Often used to form comprehensive error messages where only a BasicIo instance is available.
- putb()
Write one byte to the IO source. Current IO position is advanced by one byte.
- read()
Overload 1:
Read data from the IO source. Reading starts at the current IO position and the position is advanced by the number of bytes read.
- Parameters:
rcount (int) – Maximum number of bytes to read. Fewer bytes may be read if rcount bytes are not available.
- Return type:
- Returns:
DataBuf instance containing the bytes read. Use the DataBuf.size_ member to find the number of bytes read. DataBuf.size_ will be 0 on failure.
Overload 2:
Read data from the IO source. Reading starts at the current IO position and the position is advanced by the number of bytes read.
- Parameters:
buf (writeable bytes-like object) – Pointer to a block of memory into which the read data is stored. The memory block must be at least rcount bytes long.
rcount (int) – Maximum number of bytes to read. Fewer bytes may be read if rcount bytes are not available.
- Return type:
- Returns:
Number of bytes read from IO source successfully;
0 if failure;
- readOrThrow()
Safe version of read() that checks for errors and throws an exception if the read was unsuccessful.
- Parameters:
buf (writeable bytes-like object) – Pointer to a block of memory into which the read data is stored. The memory block must be at least rcount bytes long.
rcount (int) – Maximum number of bytes to read. Fewer bytes may be read if rcount bytes are not available.
err (ErrorCode, optional) – Error code to use if an exception is thrown.
- seek()
Move the current IO position.
- Parameters:
offset (int) – Number of bytes to move the position relative to the starting position specified by pos
pos (
BasicIo.Position) – Position from which the seek should start
- Return type:
- Returns:
0 if successful;
Nonzero if failure;
- seekOrThrow()
Safe version of seek() that checks for errors and throws an exception if the seek was unsuccessful.
- Parameters:
offset (int) – Number of bytes to move the position relative to the starting position specified by pos
pos (
BasicIo.Position) – Position from which the seek should starterr (ErrorCode) – Error code to use if an exception is thrown.
- size()
Get the current size of the IO source in bytes.
- Return type:
- Returns:
Size of the IO source in bytes;
-1 if failure;
- transfer()
Remove all data from this object’s IO source and then transfer data from the src BasicIo object into this object.
The source object is invalidated by this operation and should not be used after this method returns. This method exists primarily to be used with the BasicIo::temporary() method.
- Parameters:
src (
BasicIo) – Reference to another BasicIo instance. The entire contents of src are transferred to this object. The src object is invalidated by the method.- Raises:
Exiv2ErrorIn case of failure
- write()
Overload 1:
Write data to the IO source. Current IO position is advanced by the number of bytes written.
- Parameters:
data (bytes-like object) – Pointer to data. Data must be at least wcount bytes long
wcount (int) – Number of bytes to be written.
- Return type:
- Returns:
Number of bytes written to IO source successfully;
0 if failure;
Overload 2:
Write data that is read from another BasicIo instance to the IO source. Current IO position is advanced by the number of bytes written.
- class FileIo
Bases:
BasicIoProvides binary file IO by implementing the BasicIo interface.
- close()
Flush and unwritten data and close the file . It is safe to call close on an already closed instance.
- Return type:
- Returns:
0 if successful;
Nonzero if failure;
- eof()
Returns true if the file position has reached the end, otherwise false.
- error()
Returns 0 if the file is in a valid state, otherwise nonzero.
- getb()
Read one byte from the file. The file position is advanced by one byte.
- Return type:
- Returns:
The byte read from the file if successful;
EOF if failure;
- isopen()
Returns true if the file is open, otherwise false.
- mmap()
Map the file into the process’s address space. The file must be open before mmap() is called. If the mapped area is writeable, changes may not be written back to the underlying file until munmap() is called. The pointer is valid only as long as the FileIo object exists.
- Parameters:
isWriteable (bool, optional) – Set to true if the mapped area should be writeable (default is false).
- Return type:
- Returns:
A pointer to the mapped area.
- Raises:
Exiv2ErrorIn case of failure.
- munmap()
Remove a mapping established with mmap(). If the mapped area is writeable, this ensures that changes are written back to the underlying file.
- Return type:
- Returns:
0 if successful;
Nonzero if failure;
- open()
Overload 1:
Open the file using the specified mode.
This method can also be used to “reopen” a file which will flush any unwritten data and reset the IO position to the start. Although files can be opened in binary or text mode, this class has only been tested carefully in binary mode.
- Parameters:
mode (str) – Specified that type of access allowed on the file. Valid values match those of the C fopen command exactly.
- Return type:
- Returns:
0 if successful;
Nonzero if failure.
Overload 2:
Open the file using the default access mode of “rb”. This method can also be used to “reopen” a file which will flush any unwritten data and reset the IO position to the start.
- Return type:
- Returns:
0 if successful;
Nonzero if failure.
- path()
Returns the path of the file
- putb()
Write one byte to the file. The file position is advanced by one byte.
- read()
Overload 1:
Read data from the file. Reading starts at the current file position and the position is advanced by the number of bytes read.
- Parameters:
rcount (int) – Maximum number of bytes to read. Fewer bytes may be read if rcount bytes are not available.
- Return type:
- Returns:
DataBuf instance containing the bytes read. Use the DataBuf.size_ member to find the number of bytes read. DataBuf.size_ will be 0 on failure.
Overload 2:
Read data from the file. Reading starts at the current file position and the position is advanced by the number of bytes read.
- Parameters:
buf (writeable bytes-like object) – Pointer to a block of memory into which the read data is stored. The memory block must be at least rcount bytes long.
rcount (int) – Maximum number of bytes to read. Fewer bytes may be read if rcount bytes are not available.
- Return type:
- Returns:
Number of bytes read from the file successfully;
0 if failure;
- seek()
Move the current IO position.
- Parameters:
offset (int) – Number of bytes to move the position relative to the starting position specified by pos
pos (
BasicIo.Position) – Position from which the seek should start
- Return type:
- Returns:
0 if successful;
Nonzero if failure;
- setPath()
close the file source and set a new path.
- size()
Flush any buffered writes and get the current file size in bytes.
- Return type:
- Returns:
Size of the file in bytes;
-1 if failure;
- transfer()
Remove the contents of the file and then transfer data from the src BasicIo object into the empty file.
This method is optimized to simply rename the source file if the source object is another FileIo instance. The source BasicIo object is invalidated by this operation and should not be used after this method returns. This method exists primarily to be used with the BasicIo::temporary() method.
Note
If the caller doesn’t have permissions to write to the file, an exception is raised and src is deleted.
- Parameters:
src (
BasicIo) – Reference to another BasicIo instance. The entire contents of src are transferred to this object. The src object is invalidated by the method.- Raises:
Exiv2ErrorIn case of failure
- write()
Overload 1:
Write data to the file. The file position is advanced by the number of bytes written.
- Parameters:
data (bytes-like object) – Pointer to data. Data must be at least wcount bytes long
wcount (int) – Number of bytes to be written.
- Return type:
- Returns:
Number of bytes written to the file successfully;
0 if failure;
Overload 2:
Write data that is read from another BasicIo instance to the file. The file position is advanced by the number of bytes written.
- class MemIo
Bases:
BasicIoProvides binary IO on blocks of memory by implementing the BasicIo interface. A copy-on-write implementation ensures that the data passed in is only copied when necessary, i.e., as soon as data is written to the MemIo. The original data is only used for reading. If writes are performed, the changed data can be retrieved using the read methods (since the data used in construction is never modified).
Note
If read only usage of this class is common, it might be worth creating a specialized readonly class or changing this one to have a readonly mode.
- eof()
Returns true if the IO position has reached the end, otherwise false.
- error()
Always returns 0
- getb()
Read one byte from the memory block. The IO position is advanced by one byte.
- Return type:
- Returns:
The byte read from the memory block if successful;
EOF if failure;
- isopen()
Always returns true
- mmap()
Allow direct access to the underlying data buffer. The buffer is not protected against write access in any way, the argument is ignored.
Note
The application must ensure that the memory pointed to by the returned pointer remains valid and allocated as long as the MemIo object exists.
- munmap()
Remove a mapping established with mmap(). If the mapped area is writeable, this ensures that changes are written back.
- Return type:
- Returns:
0 if successful;
Nonzero if failure;
- open()
Memory IO is always open for reading and writing. This method therefore only resets the IO position to the start.
- Return type:
- Returns:
0
- path()
Returns a dummy path, indicating that memory access is used
- putb()
Write one byte to the memory block. The IO position is advanced by one byte.
- read()
Overload 1:
Read data from the memory block. Reading starts at the current IO position and the position is advanced by the number of bytes read.
- Parameters:
rcount (int) – Maximum number of bytes to read. Fewer bytes may be read if rcount bytes are not available.
- Return type:
- Returns:
DataBuf instance containing the bytes read. Use the DataBuf.size_ member to find the number of bytes read. DataBuf.size_ will be 0 on failure.
Overload 2:
Read data from the memory block. Reading starts at the current IO position and the position is advanced by the number of bytes read.
- Parameters:
buf (writeable bytes-like object) – Pointer to a block of memory into which the read data is stored. The memory block must be at least rcount bytes long.
rcount (int) – Maximum number of bytes to read. Fewer bytes may be read if rcount bytes are not available.
- Return type:
- Returns:
Number of bytes read from the memory block successfully;
0 if failure;
- seek()
Move the current IO position.
- Parameters:
offset (int) – Number of bytes to move the position relative to the starting position specified by pos
pos (
BasicIo.Position) – Position from which the seek should start
- Return type:
- Returns:
0 if successful;
Nonzero if failure;
- size()
Get the current memory buffer size in bytes.
- Return type:
- Returns:
Size of the in memory data in bytes;
-1 if failure;
- tell()
Get the current IO position.
- Return type:
- Returns:
Offset from the start of the memory block
- transfer()
Clear the memory block and then transfer data from the src BasicIo object into a new block of memory.
This method is optimized to simply swap memory block if the source object is another MemIo instance. The source BasicIo instance is invalidated by this operation and should not be used after this method returns. This method exists primarily to be used with the BasicIo::temporary() method.
- Parameters:
src (
BasicIo) – Reference to another BasicIo instance. The entire contents of src are transferred to this object. The src object is invalidated by the method.- Raises:
Exiv2ErrorIn case of failure
- write()
Overload 1:
Write data to the memory block. If needed, the size of the internal memory block is expanded. The IO position is advanced by the number of bytes written.
- Parameters:
data (bytes-like object) – Pointer to data. Data must be at least wcount bytes long
wcount (int) – Number of bytes to be written.
- Return type:
- Returns:
Number of bytes written to the memory block successfully;
0 if failure;
Overload 2:
Write data that is read from another BasicIo instance to the memory block. If needed, the size of the internal memory block is expanded. The IO position is advanced by the number of bytes written.
- class RemoteIo
Bases:
BasicIoProvides remote binary file IO by implementing the BasicIo interface. This is an abstract class. The logics for remote access are implemented in HttpIo, CurlIo, SshIo which are the derived classes of RemoteIo.
- close()
Reset the IO position to the start. It does not release the data.
- Return type:
- Returns:
0 if successful;
Nonzero if failure.
- eof()
Returns true if the IO position has reached the end, otherwise false.
- error()
Always returns 0
- getb()
Read one byte from the memory blocks. The IO position is advanced by one byte. If the memory block is not populated (!= bMemory), it will connect to server and populate the data to the memory block.
- Return type:
- Returns:
The byte read from the memory block if successful;
EOF if failure;
- isopen()
Returns true if the memory area is allocated.
- mmap()
Not support
- Return type:
- Returns:
NULL
- open()
Connect to the remote server, get the size of the remote file and allocate the array of blocksMap.
If the blocksMap is already allocated (this method has been called before), it just reset IO position to the start and does not flush the old data.
- Return type:
- Returns:
0 if successful;
Nonzero if failure.
- path()
Returns the URL of the file.
- read()
Overload 1:
Read data from the memory blocks. Reading starts at the current IO position and the position is advanced by the number of bytes read. If the memory blocks are not populated (False), it will connect to server and populate the data to memory blocks.
- Parameters:
rcount (int) – Maximum number of bytes to read. Fewer bytes may be read if rcount bytes are not available.
- Return type:
- Returns:
DataBuf instance containing the bytes read. Use the DataBuf.size_ member to find the number of bytes read. DataBuf.size_ will be 0 on failure.
Overload 2:
Read data from the memory blocks. Reading starts at the current IO position and the position is advanced by the number of bytes read. If the memory blocks are not populated (!= bMemory), it will connect to server and populate the data to memory blocks.
- Parameters:
buf (writeable bytes-like object) – Pointer to a block of memory into which the read data is stored. The memory block must be at least rcount bytes long.
rcount (int) – Maximum number of bytes to read. Fewer bytes may be read if rcount bytes are not available.
- Return type:
- Returns:
Number of bytes read from the memory block successfully;
0 if failure;
- seek()
Move the current IO position.
- Parameters:
offset (int) – Number of bytes to move the position relative to the starting position specified by pos
pos (
BasicIo.Position) – Position from which the seek should start
- Return type:
- Returns:
0 if successful;
Nonzero if failure;
- size()
Get the current memory buffer size in bytes.
- Return type:
- Returns:
Size of the in memory data in bytes;
-1 if failure;
- tell()
Get the current IO position.
- Return type:
- Returns:
Offset from the start of the memory block
- transfer()
Remove the contents of the file and then transfer data from the src BasicIo object into the empty file.
The write access is done in an efficient way. It only sends the range of different bytes between the current data and BasicIo instance to the remote machine.
- Parameters:
src (
BasicIo) – Reference to another BasicIo instance. The entire contents of src are transferred to this object. The src object is invalidated by the method.- Raises:
Exiv2ErrorIn case of failure
Note
The write access is only supported by http, https, ssh.
- write()
Overload 1:
Not support this method.
- Return type:
- Returns:
0 means failure
Overload 2:
Write data that is read from another BasicIo instance to the remote file.
The write access is done in an efficient way. It only sends the range of different bytes between the current data and BasicIo instance to the remote machine.
- Parameters:
src (
BasicIo) – Reference to another BasicIo instance. Reading start at the source’s current IO position- Return type:
- Returns:
The size of BasicIo instance;
0 if failure;
- Raises:
Exiv2ErrorIn case of failure
Note
The write access is only supported by http, https, ssh.
- class XPathIo
Bases:
FileIoProvides binary IO for the data from stdin and data uri path.
- transfer()
Change the name of the temp file and make it untemporary before calling the method of superclass FileIo::transfer.
- static writeDataToFile()
Read the data from stdin/data uri path and write them to the file.
- Parameters:
orgPath (str) – It equals “-” if the input data’s from stdin. Otherwise, it’s data uri path.
- Return type:
- Returns:
the name of the new file.
- Raises:
Exiv2Errorif it fails.