Skip to content

Commit bafcb95

Browse files
jim-easterbrookjim-easterbrook
committed
Improved docs relating to BasicIo
1 parent b3a7b22 commit bafcb95

File tree

9 files changed

+185
-47
lines changed

9 files changed

+185
-47
lines changed

‎USAGE.rst‎

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -387,8 +387,8 @@ Doing so will invalidate the memoryview and may cause a segmentation fault:
387387
Buffer interface
388388
----------------
389389

390-
The ``Exiv2::DataBuf``, ``Exiv2::PreviewImage``, and ``Exiv2::MemIO`` classes are all wrappers around a potentially large block of memory.
391-
They each have methods to access that memory without copying, such as ``Exiv2::DataBuf::data()`` and ``Exiv2::MemIo::mmap()`` but in Python these classes also expose a `buffer interface`_. This allows them to be used almost anywhere that a `bytes-like object`_ is expected.
390+
The ``Exiv2::DataBuf``, ``Exiv2::PreviewImage``, and ``Exiv2::BasicIO`` classes are all wrappers around a potentially large block of memory.
391+
They each have methods to access that memory without copying, such as ``Exiv2::DataBuf::data()`` and ``Exiv2::BasicIo::mmap()`` but in Python these classes also expose a `buffer interface`_. This allows them to be used almost anywhere that a `bytes-like object`_ is expected.
392392

393393
For example, you could save a photograph's thumbnail in a separate file like this:
394394

@@ -406,8 +406,7 @@ In python-exiv2 the ``data`` and ``size`` parameters are replaced with a single
406406
The buffered data isn't actually read until ``Image::readMetadata`` is called, so python-exiv2 stores a reference to the buffer to stop the user accidentally deleting it.
407407

408408
When ``Image::writeMetadata`` is called exiv2 allocates a new block of memory to store the modified data.
409-
The ``Image::io`` method returns an `Exiv2::MemIo`_ object that provides access to this data.
410-
(`Exiv2::MemIo`_ is derived from `Exiv2::BasicIo`_.)
409+
The ``Image::io`` method returns an `Exiv2::BasicIo`_ object that provides access to this data.
411410

412411
The ``BasicIo::mmap`` method allows access to the image file data without unnecessary copying.
413412
However it is rather error prone, crashing your Python program with a segmentation fault if anything goes wrong.
@@ -453,7 +452,7 @@ Since python-exiv2 v0.15.0 this buffer can be writeable:
453452
data[23] = 157 # modifies data buffer
454453
image.readMetadata() # reads modified buffer data
455454
456-
The modified data is written back to the file (for ``Exiv2::FileIo``) or memory buffer (for `Exiv2::MemIo`_) when the memoryview_ is released.
455+
The modified data is written back to the file or memory buffer when the memoryview_ is released.
457456

458457
.. _bytearray:
459458
https://docs.python.org/3/library/stdtypes.html#bytearray
@@ -483,8 +482,6 @@ The modified data is written back to the file (for ``Exiv2::FileIo``) or memory
483482
https://exiv2.org/doc/classExiv2_1_1Image.html
484483
.. _Exiv2::ImageFactory:
485484
https://exiv2.org/doc/classExiv2_1_1ImageFactory.html
486-
.. _Exiv2::MemIo:
487-
https://exiv2.org/doc/classExiv2_1_1MemIo.html
488485
.. _Exiv2::Metadatum:
489486
https://exiv2.org/doc/classExiv2_1_1Metadatum.html
490487
.. _Exiv2::TagInfo:

‎src/interface/basicio.i‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@ WINDOWS_PATH_OUT(path)
7070
You shouldn't usually need to know the type of IO as they all have
7171
the same interface.
7272
:rtype: str
73-
:return: A class name such as ""FileIo""."
73+
:return: A class name such as \"FileIo\"."
7474
%extend Exiv2::BasicIo {
7575
const char* ioType() {
7676
if (dynamic_cast<Exiv2::MemIo*>($self))

‎src/interface/image.i‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,39 @@ WINDOWS_PATH(const std::string& path)
8888
%ignore Exiv2::enableBMFF();
8989

9090
// Extend ImageFactory to allow creation of a MemIo from a buffer
91+
%feature("docstring") Exiv2::ImageFactory::createIo "
92+
*Overload 1:*
93+
94+
Create the appropriate class type implemented BasicIo based on the
95+
protocol of the input.
96+
97+
\"-\" path implies the data from stdin and it is handled by StdinIo.
98+
Http path can be handled by either HttpIo or CurlIo. Https, ftp paths
99+
are handled by CurlIo. Ssh, sftp paths are handled by SshIo. Others are
100+
handled by FileIo.
101+
102+
:type path: str
103+
:param path: %Image file.
104+
:type useCurl: bool, optional
105+
:param useCurl: Indicate whether the libcurl is used or not.
106+
If it's true, http is handled by CurlIo. Otherwise it is
107+
handled by HttpIo.
108+
:rtype: :py:class:`BasicIo`
109+
:return: An auto-pointer that owns a BasicIo instance.
110+
:raises: Error If the file is not found or it is unable to connect to
111+
the server to read the remote file.
112+
113+
|
114+
115+
*Overload 2:*
116+
117+
Create a MemIo subclass of BasicIo using the provided memory.
118+
119+
:type data: :py:term:`bytes-like object`
120+
:param data: A data buffer.
121+
:rtype: :py:class:`BasicIo`
122+
:return: A BasicIo object.
123+
"
91124
%extend Exiv2::ImageFactory {
92125
static Exiv2::BasicIo::SMART_PTR createIo(
93126
const Exiv2::byte* data, size_t B) {

‎src/swig-0_27_3/basicio_wrap.cxx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5737,7 +5737,7 @@ SWIGINTERN PyMethodDef SwigPyBuiltin__Exiv2__BasicIo_methods[] = {
57375737
"You shouldn't usually need to know the type of IO as they all have\n"
57385738
"the same interface.\n"
57395739
":rtype: str\n"
5740-
":return: A class name such as FileIo.\n"
5740+
":return: A class name such as \"FileIo\".\n"
57415741
"" },
57425742
{ NULL, NULL, 0, NULL } /* Sentinel */
57435743
};

‎src/swig-0_27_3/image_wrap.cxx‎

Lines changed: 48 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -7525,21 +7525,39 @@ SWIGINTERN SwigPyClientData SwigPyBuiltin__Exiv2__Image_clientdata = {0, 0, 0, 0
75257525
static SwigPyGetSet ImageFactory___dict___getset = { SwigPyObject_get___dict__, 0 };
75267526
SWIGINTERN PyGetSetDef SwigPyBuiltin__Exiv2__ImageFactory_getset[] = {
75277527
{ (char *)"__dict__", SwigPyBuiltin_FunpackGetterClosure, 0, (char *)"\n"
7528-
"Create the appropriate class type implemented BasicIo based on the protocol of the input.\n"
7528+
"\n"
7529+
"*Overload 1:*\n"
7530+
"\n"
7531+
"Create the appropriate class type implemented BasicIo based on the\n"
7532+
"protocol of the input.\n"
75297533
"\n"
75307534
"\"-\" path implies the data from stdin and it is handled by StdinIo.\n"
75317535
"Http path can be handled by either HttpIo or CurlIo. Https, ftp paths\n"
7532-
"are handled by CurlIo. Ssh, sftp paths are handled by SshIo. Others are handled by FileIo.\n"
7536+
"are handled by CurlIo. Ssh, sftp paths are handled by SshIo. Others are\n"
7537+
"handled by FileIo.\n"
75337538
"\n"
75347539
":type path: str\n"
75357540
":param path: %Image file.\n"
75367541
":type useCurl: bool, optional\n"
75377542
":param useCurl: Indicate whether the libcurl is used or not.\n"
7538-
" If it's true, http is handled by CurlIo. Otherwise it is handled by HttpIo.\n"
7543+
" If it's true, http is handled by CurlIo. Otherwise it is\n"
7544+
" handled by HttpIo.\n"
75397545
":rtype: :py:class:`BasicIo`\n"
7540-
":return: An auto-pointer that owns an BasicIo instance.\n"
7541-
":raises: Error If the file is not found or it is unable to connect to the server to\n"
7542-
" read the remote file.\n"
7546+
":return: An auto-pointer that owns a BasicIo instance.\n"
7547+
":raises: Error If the file is not found or it is unable to connect to\n"
7548+
" the server to read the remote file.\n"
7549+
"\n"
7550+
"|\n"
7551+
"\n"
7552+
"*Overload 2:*\n"
7553+
"\n"
7554+
"Create a MemIo subclass of BasicIo using the provided memory.\n"
7555+
"\n"
7556+
":type data: :py:term:`bytes-like object`\n"
7557+
":param data: A data buffer.\n"
7558+
":rtype: :py:class:`BasicIo`\n"
7559+
":return: A BasicIo object.\n"
7560+
"\n"
75437561
"", &ImageFactory___dict___getset },
75447562
{ NULL, NULL, NULL, NULL, NULL } /* Sentinel */
75457563
};
@@ -7560,21 +7578,39 @@ SwigPyBuiltin__Exiv2__ImageFactory_richcompare(PyObject *self, PyObject *other,
75607578

75617579
SWIGINTERN PyMethodDef SwigPyBuiltin__Exiv2__ImageFactory_methods[] = {
75627580
{ "createIo", (PyCFunction)(void(*)(void))_wrap_ImageFactory_createIo, METH_STATIC|METH_VARARGS, "\n"
7563-
"Create the appropriate class type implemented BasicIo based on the protocol of the input.\n"
7581+
"\n"
7582+
"*Overload 1:*\n"
7583+
"\n"
7584+
"Create the appropriate class type implemented BasicIo based on the\n"
7585+
"protocol of the input.\n"
75647586
"\n"
75657587
"\"-\" path implies the data from stdin and it is handled by StdinIo.\n"
75667588
"Http path can be handled by either HttpIo or CurlIo. Https, ftp paths\n"
7567-
"are handled by CurlIo. Ssh, sftp paths are handled by SshIo. Others are handled by FileIo.\n"
7589+
"are handled by CurlIo. Ssh, sftp paths are handled by SshIo. Others are\n"
7590+
"handled by FileIo.\n"
75687591
"\n"
75697592
":type path: str\n"
75707593
":param path: %Image file.\n"
75717594
":type useCurl: bool, optional\n"
75727595
":param useCurl: Indicate whether the libcurl is used or not.\n"
7573-
" If it's true, http is handled by CurlIo. Otherwise it is handled by HttpIo.\n"
7596+
" If it's true, http is handled by CurlIo. Otherwise it is\n"
7597+
" handled by HttpIo.\n"
75747598
":rtype: :py:class:`BasicIo`\n"
7575-
":return: An auto-pointer that owns an BasicIo instance.\n"
7576-
":raises: Error If the file is not found or it is unable to connect to the server to\n"
7577-
" read the remote file.\n"
7599+
":return: An auto-pointer that owns a BasicIo instance.\n"
7600+
":raises: Error If the file is not found or it is unable to connect to\n"
7601+
" the server to read the remote file.\n"
7602+
"\n"
7603+
"|\n"
7604+
"\n"
7605+
"*Overload 2:*\n"
7606+
"\n"
7607+
"Create a MemIo subclass of BasicIo using the provided memory.\n"
7608+
"\n"
7609+
":type data: :py:term:`bytes-like object`\n"
7610+
":param data: A data buffer.\n"
7611+
":rtype: :py:class:`BasicIo`\n"
7612+
":return: A BasicIo object.\n"
7613+
"\n"
75787614
"" },
75797615
{ "open", (PyCFunction)(void(*)(void))_wrap_ImageFactory_open, METH_STATIC|METH_VARARGS, "\n"
75807616
"*Overload 1:*\n"

‎src/swig-0_27_7/basicio_wrap.cxx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5737,7 +5737,7 @@ SWIGINTERN PyMethodDef SwigPyBuiltin__Exiv2__BasicIo_methods[] = {
57375737
"You shouldn't usually need to know the type of IO as they all have\n"
57385738
"the same interface.\n"
57395739
":rtype: str\n"
5740-
":return: A class name such as FileIo.\n"
5740+
":return: A class name such as \"FileIo\".\n"
57415741
"" },
57425742
{ NULL, NULL, 0, NULL } /* Sentinel */
57435743
};

‎src/swig-0_27_7/image_wrap.cxx‎

Lines changed: 48 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -7525,21 +7525,39 @@ SWIGINTERN SwigPyClientData SwigPyBuiltin__Exiv2__Image_clientdata = {0, 0, 0, 0
75257525
static SwigPyGetSet ImageFactory___dict___getset = { SwigPyObject_get___dict__, 0 };
75267526
SWIGINTERN PyGetSetDef SwigPyBuiltin__Exiv2__ImageFactory_getset[] = {
75277527
{ (char *)"__dict__", SwigPyBuiltin_FunpackGetterClosure, 0, (char *)"\n"
7528-
"Create the appropriate class type implemented BasicIo based on the protocol of the input.\n"
7528+
"\n"
7529+
"*Overload 1:*\n"
7530+
"\n"
7531+
"Create the appropriate class type implemented BasicIo based on the\n"
7532+
"protocol of the input.\n"
75297533
"\n"
75307534
"\"-\" path implies the data from stdin and it is handled by StdinIo.\n"
75317535
"Http path can be handled by either HttpIo or CurlIo. Https, ftp paths\n"
7532-
"are handled by CurlIo. Ssh, sftp paths are handled by SshIo. Others are handled by FileIo.\n"
7536+
"are handled by CurlIo. Ssh, sftp paths are handled by SshIo. Others are\n"
7537+
"handled by FileIo.\n"
75337538
"\n"
75347539
":type path: str\n"
75357540
":param path: %Image file.\n"
75367541
":type useCurl: bool, optional\n"
75377542
":param useCurl: Indicate whether the libcurl is used or not.\n"
7538-
" If it's true, http is handled by CurlIo. Otherwise it is handled by HttpIo.\n"
7543+
" If it's true, http is handled by CurlIo. Otherwise it is\n"
7544+
" handled by HttpIo.\n"
75397545
":rtype: :py:class:`BasicIo`\n"
7540-
":return: An auto-pointer that owns an BasicIo instance.\n"
7541-
":raises: Error If the file is not found or it is unable to connect to the server to\n"
7542-
" read the remote file.\n"
7546+
":return: An auto-pointer that owns a BasicIo instance.\n"
7547+
":raises: Error If the file is not found or it is unable to connect to\n"
7548+
" the server to read the remote file.\n"
7549+
"\n"
7550+
"|\n"
7551+
"\n"
7552+
"*Overload 2:*\n"
7553+
"\n"
7554+
"Create a MemIo subclass of BasicIo using the provided memory.\n"
7555+
"\n"
7556+
":type data: :py:term:`bytes-like object`\n"
7557+
":param data: A data buffer.\n"
7558+
":rtype: :py:class:`BasicIo`\n"
7559+
":return: A BasicIo object.\n"
7560+
"\n"
75437561
"", &ImageFactory___dict___getset },
75447562
{ NULL, NULL, NULL, NULL, NULL } /* Sentinel */
75457563
};
@@ -7560,21 +7578,39 @@ SwigPyBuiltin__Exiv2__ImageFactory_richcompare(PyObject *self, PyObject *other,
75607578

75617579
SWIGINTERN PyMethodDef SwigPyBuiltin__Exiv2__ImageFactory_methods[] = {
75627580
{ "createIo", (PyCFunction)(void(*)(void))_wrap_ImageFactory_createIo, METH_STATIC|METH_VARARGS, "\n"
7563-
"Create the appropriate class type implemented BasicIo based on the protocol of the input.\n"
7581+
"\n"
7582+
"*Overload 1:*\n"
7583+
"\n"
7584+
"Create the appropriate class type implemented BasicIo based on the\n"
7585+
"protocol of the input.\n"
75647586
"\n"
75657587
"\"-\" path implies the data from stdin and it is handled by StdinIo.\n"
75667588
"Http path can be handled by either HttpIo or CurlIo. Https, ftp paths\n"
7567-
"are handled by CurlIo. Ssh, sftp paths are handled by SshIo. Others are handled by FileIo.\n"
7589+
"are handled by CurlIo. Ssh, sftp paths are handled by SshIo. Others are\n"
7590+
"handled by FileIo.\n"
75687591
"\n"
75697592
":type path: str\n"
75707593
":param path: %Image file.\n"
75717594
":type useCurl: bool, optional\n"
75727595
":param useCurl: Indicate whether the libcurl is used or not.\n"
7573-
" If it's true, http is handled by CurlIo. Otherwise it is handled by HttpIo.\n"
7596+
" If it's true, http is handled by CurlIo. Otherwise it is\n"
7597+
" handled by HttpIo.\n"
75747598
":rtype: :py:class:`BasicIo`\n"
7575-
":return: An auto-pointer that owns an BasicIo instance.\n"
7576-
":raises: Error If the file is not found or it is unable to connect to the server to\n"
7577-
" read the remote file.\n"
7599+
":return: An auto-pointer that owns a BasicIo instance.\n"
7600+
":raises: Error If the file is not found or it is unable to connect to\n"
7601+
" the server to read the remote file.\n"
7602+
"\n"
7603+
"|\n"
7604+
"\n"
7605+
"*Overload 2:*\n"
7606+
"\n"
7607+
"Create a MemIo subclass of BasicIo using the provided memory.\n"
7608+
"\n"
7609+
":type data: :py:term:`bytes-like object`\n"
7610+
":param data: A data buffer.\n"
7611+
":rtype: :py:class:`BasicIo`\n"
7612+
":return: A BasicIo object.\n"
7613+
"\n"
75787614
"" },
75797615
{ "open", (PyCFunction)(void(*)(void))_wrap_ImageFactory_open, METH_STATIC|METH_VARARGS, "\n"
75807616
"*Overload 1:*\n"

‎src/swig-0_28_2/basicio_wrap.cxx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6027,7 +6027,7 @@ SWIGINTERN PyMethodDef SwigPyBuiltin__Exiv2__BasicIo_methods[] = {
60276027
"You shouldn't usually need to know the type of IO as they all have\n"
60286028
"the same interface.\n"
60296029
":rtype: str\n"
6030-
":return: A class name such as FileIo.\n"
6030+
":return: A class name such as \"FileIo\".\n"
60316031
"" },
60326032
{ NULL, NULL, 0, NULL } /* Sentinel */
60336033
};

‎src/swig-0_28_2/image_wrap.cxx‎

Lines changed: 48 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -7538,21 +7538,39 @@ SWIGINTERN SwigPyClientData SwigPyBuiltin__Exiv2__Image_clientdata = {0, 0, 0, 0
75387538
static SwigPyGetSet ImageFactory___dict___getset = { SwigPyObject_get___dict__, 0 };
75397539
SWIGINTERN PyGetSetDef SwigPyBuiltin__Exiv2__ImageFactory_getset[] = {
75407540
{ (char *)"__dict__", SwigPyBuiltin_FunpackGetterClosure, 0, (char *)"\n"
7541-
"Create the appropriate class type implemented BasicIo based on the protocol of the input.\n"
7541+
"\n"
7542+
"*Overload 1:*\n"
7543+
"\n"
7544+
"Create the appropriate class type implemented BasicIo based on the\n"
7545+
"protocol of the input.\n"
75427546
"\n"
75437547
"\"-\" path implies the data from stdin and it is handled by StdinIo.\n"
75447548
"Http path can be handled by either HttpIo or CurlIo. Https, ftp paths\n"
7545-
"are handled by CurlIo. Ssh, sftp paths are handled by SshIo. Others are handled by FileIo.\n"
7549+
"are handled by CurlIo. Ssh, sftp paths are handled by SshIo. Others are\n"
7550+
"handled by FileIo.\n"
75467551
"\n"
75477552
":type path: str\n"
75487553
":param path: %Image file.\n"
75497554
":type useCurl: bool, optional\n"
75507555
":param useCurl: Indicate whether the libcurl is used or not.\n"
7551-
" If it's true, http is handled by CurlIo. Otherwise it is handled by HttpIo.\n"
7556+
" If it's true, http is handled by CurlIo. Otherwise it is\n"
7557+
" handled by HttpIo.\n"
75527558
":rtype: :py:class:`BasicIo`\n"
7553-
":return: An auto-pointer that owns an BasicIo instance.\n"
7554-
":raises: Error If the file is not found or it is unable to connect to the server to\n"
7555-
" read the remote file.\n"
7559+
":return: An auto-pointer that owns a BasicIo instance.\n"
7560+
":raises: Error If the file is not found or it is unable to connect to\n"
7561+
" the server to read the remote file.\n"
7562+
"\n"
7563+
"|\n"
7564+
"\n"
7565+
"*Overload 2:*\n"
7566+
"\n"
7567+
"Create a MemIo subclass of BasicIo using the provided memory.\n"
7568+
"\n"
7569+
":type data: :py:term:`bytes-like object`\n"
7570+
":param data: A data buffer.\n"
7571+
":rtype: :py:class:`BasicIo`\n"
7572+
":return: A BasicIo object.\n"
7573+
"\n"
75567574
"", &ImageFactory___dict___getset },
75577575
{ NULL, NULL, NULL, NULL, NULL } /* Sentinel */
75587576
};
@@ -7573,21 +7591,39 @@ SwigPyBuiltin__Exiv2__ImageFactory_richcompare(PyObject *self, PyObject *other,
75737591

75747592
SWIGINTERN PyMethodDef SwigPyBuiltin__Exiv2__ImageFactory_methods[] = {
75757593
{ "createIo", (PyCFunction)(void(*)(void))_wrap_ImageFactory_createIo, METH_STATIC|METH_VARARGS, "\n"
7576-
"Create the appropriate class type implemented BasicIo based on the protocol of the input.\n"
7594+
"\n"
7595+
"*Overload 1:*\n"
7596+
"\n"
7597+
"Create the appropriate class type implemented BasicIo based on the\n"
7598+
"protocol of the input.\n"
75777599
"\n"
75787600
"\"-\" path implies the data from stdin and it is handled by StdinIo.\n"
75797601
"Http path can be handled by either HttpIo or CurlIo. Https, ftp paths\n"
7580-
"are handled by CurlIo. Ssh, sftp paths are handled by SshIo. Others are handled by FileIo.\n"
7602+
"are handled by CurlIo. Ssh, sftp paths are handled by SshIo. Others are\n"
7603+
"handled by FileIo.\n"
75817604
"\n"
75827605
":type path: str\n"
75837606
":param path: %Image file.\n"
75847607
":type useCurl: bool, optional\n"
75857608
":param useCurl: Indicate whether the libcurl is used or not.\n"
7586-
" If it's true, http is handled by CurlIo. Otherwise it is handled by HttpIo.\n"
7609+
" If it's true, http is handled by CurlIo. Otherwise it is\n"
7610+
" handled by HttpIo.\n"
75877611
":rtype: :py:class:`BasicIo`\n"
7588-
":return: An auto-pointer that owns an BasicIo instance.\n"
7589-
":raises: Error If the file is not found or it is unable to connect to the server to\n"
7590-
" read the remote file.\n"
7612+
":return: An auto-pointer that owns a BasicIo instance.\n"
7613+
":raises: Error If the file is not found or it is unable to connect to\n"
7614+
" the server to read the remote file.\n"
7615+
"\n"
7616+
"|\n"
7617+
"\n"
7618+
"*Overload 2:*\n"
7619+
"\n"
7620+
"Create a MemIo subclass of BasicIo using the provided memory.\n"
7621+
"\n"
7622+
":type data: :py:term:`bytes-like object`\n"
7623+
":param data: A data buffer.\n"
7624+
":rtype: :py:class:`BasicIo`\n"
7625+
":return: A BasicIo object.\n"
7626+
"\n"
75917627
"" },
75927628
{ "open", (PyCFunction)(void(*)(void))_wrap_ImageFactory_open, METH_STATIC|METH_VARARGS, "\n"
75937629
"*Overload 1:*\n"

0 commit comments

Comments
 (0)