improve the documentation

closes #26, closes #92, closes #112

Author: Changaco

README.rst

@@ -36,32 +36,87 @@ Import::
 
     import libarchive
 
-To extract an archive to the current directory::
+Extracting archives
+-------------------
 
+To extract an archive, use the ``extract_file`` function::
+
+    os.chdir('/path/to/target/directory')
     libarchive.extract_file('test.zip')
 
-``extract_memory`` extracts from a buffer instead, and ``extract_fd`` extracts
-from a file descriptor.
+Alternatively, the ``extract_memory`` function can be used to extract from a buffer,
+and ``extract_fd`` from a file descriptor.
+
+The ``extract_*`` functions all have an integer ``flags`` argument which is passed
+directly to the C function ``archive_write_disk_set_options()``. You can import
+the ``EXTRACT_*`` constants from the ``libarchive.extract`` module and see the
+official description of each flag in the ``archive_write_disk(3)`` man page.
+
+By default, when the ``flags`` argument is ``None``, the ``SECURE_NODOTDOT``,
+``SECURE_NOABSOLUTEPATHS`` and ``SECURE_SYMLINKS`` flags are passed to
+libarchive, unless the current directory is the root (``/``).
+
+Reading archives
+----------------
 
-To read an archive::
+To read an archive, use the ``file_reader`` function::
 
     with libarchive.file_reader('test.7z') as archive:
         for entry in archive:
             for block in entry.get_blocks():
                 ...
 
-``memory_reader`` reads from a memory buffer instead, and ``fd_reader`` reads
-from a file descriptor.
+Alternatively, the ``memory_reader`` function can be used to read from a buffer,
+``fd_reader`` from a file descriptor, ``stream_reader`` from a stream object
+(which must support the standard ``readinto`` method), and ``custom_reader``
+from anywhere using callbacks.
 
-To create an archive::
+To learn about the attributes of the ``entry`` object, see the ``libarchive/entry.py``
+source code or run ``help(libarchive.entry.ArchiveEntry)`` in a Python shell.
 
-    with libarchive.file_writer('test.tar.gz', 'ustar', 'gzip') as archive:
-        archive.add_files('libarchive/', 'README.rst')
+Displaying progress
+~~~~~~~~~~~~~~~~~~~
+
+The ``stream_reader`` function and the standard `tell <https://docs.python.org/3/library/io.html#io.IOBase.tell>`_ method can be used to estimate how much of an archive has been read by your program. Here's an example of a progress bar using `tqdm <https://pypi.org/project/tqdm/>`_::
 
-``memory_writer`` writes to a memory buffer instead, ``fd_writer`` writes to a
-file descriptor, and ``custom_writer`` sends the data to a callback function.
+    with tqdm(total=os.stat(archive_path).st_size, unit='bytes') as pbar, \
+         open(archive_path, 'rb') as file, \
+         libarchive.stream_reader(file) as archive:
+        for entry in archive:
+            ...
+            pbar.update(file.tell() - pbar.n)
+
+Of course this is only useful if your program processes large archives.
+
+Creating archives
+-----------------
+
+To create an archive, use the ``file_writer`` function::
 
-You can also find more thorough examples in the ``tests/`` directory.
+    from libarchive.entry import FileType
+
+    with libarchive.file_writer('test.tar.gz', 'ustar', 'gzip') as archive:
+        # Add the `libarchive/` directory and everything in it (recursively),
+        # then the `README.rst` file.
+        archive.add_files('libarchive/', 'README.rst')
+        # Add a regular file defined from scratch.
+        data = b'foobar'
+        archive.add_file_from_memory('../escape-test', len(data), data)
+        # Add a directory defined from scratch.
+        early_epoch = (42, 42)  # 1970-01-01 00:00:42.000000042
+        archive.add_file_from_memory(
+            'metadata-test', 0, b'',
+            filetype=FileType.DIRECTORY, permission=0o755, uid=4242, gid=4242,
+            atime=early_epoch, mtime=early_epoch, ctime=early_epoch, birthtime=early_epoch,
+        )
+
+Alternatively, the ``memory_writer`` function can be used to write to a memory buffer,
+``fd_writer`` to a file descriptor, and ``custom_writer`` to a callback function.
+
+For each of those functions, the mandatory second argument is the archive format,
+and the optional third argument is the compression format (called “filter” in
+libarchive). The acceptable values are listed in ``libarchive.ffi.WRITE_FORMATS``
+and ``libarchive.ffi.WRITE_FILTERS``.
 
 License
 =======

libarchive/entry.py

@@ -47,9 +47,11 @@ def __init__(self, archive_p=None, **attributes):
             self.modify(**attributes)
 
     def __del__(self):
+        """Free the C struct"""
         ffi.entry_free(self._entry_p)
 
     def __str__(self):
+        """Returns the file's path"""
         return self.pathname
 
     def modify(self, **attributes):
@@ -129,7 +131,16 @@ def gname(self, value):
         ffi.entry_update_gname_utf8(self._entry_p, value)
 
     def get_blocks(self, block_size=ffi.page_size):
+        """Read the file's content, keeping only one chunk in memory at a time.
+
+        Don't do anything like `list(entry.get_blocks())`, it would silently fail.
+
+        Args:
+            block_size (int): the buffer's size, in bytes
+        """
         archive_p = self._archive_p
+        if not archive_p:
+            raise TypeError("this entry isn't linked to any content")
         buf = create_string_buffer(block_size)
         read = ffi.read_data
         while 1:
@@ -200,8 +211,8 @@ def atime(self, value):
             self.set_atime(int(seconds), int(fraction * 1_000_000_000))
 
     def set_atime(self, timestamp_sec, timestamp_nsec):
-        return ffi.entry_set_atime(self._entry_p,
-                                   timestamp_sec, timestamp_nsec)
+        "Kept for backward compatibility. `entry.atime = ...` is supported now."
+        return ffi.entry_set_atime(self._entry_p, timestamp_sec, timestamp_nsec)
 
     @property
     def mtime(self):
@@ -224,8 +235,8 @@ def mtime(self, value):
             self.set_mtime(int(seconds), int(fraction * 1_000_000_000))
 
     def set_mtime(self, timestamp_sec, timestamp_nsec):
-        return ffi.entry_set_mtime(self._entry_p,
-                                   timestamp_sec, timestamp_nsec)
+        "Kept for backward compatibility. `entry.mtime = ...` is supported now."
+        return ffi.entry_set_mtime(self._entry_p, timestamp_sec, timestamp_nsec)
 
     @property
     def ctime(self):
@@ -248,8 +259,8 @@ def ctime(self, value):
             self.set_ctime(int(seconds), int(fraction * 1_000_000_000))
 
     def set_ctime(self, timestamp_sec, timestamp_nsec):
-        return ffi.entry_set_ctime(self._entry_p,
-                                   timestamp_sec, timestamp_nsec)
+        "Kept for backward compatibility. `entry.ctime = ...` is supported now."
+        return ffi.entry_set_ctime(self._entry_p, timestamp_sec, timestamp_nsec)
 
     @property
     def birthtime(self):
@@ -272,6 +283,7 @@ def birthtime(self, value):
             self.set_birthtime(int(seconds), int(fraction * 1_000_000_000))
 
     def set_birthtime(self, timestamp_sec, timestamp_nsec=0):
+        "Kept for backward compatibility. `entry.birthtime = ...` is supported now."
         return ffi.entry_set_birthtime(
             self._entry_p, timestamp_sec, timestamp_nsec
         )
@@ -331,6 +343,7 @@ def mode(self, value):
 
     @property
     def strmode(self):
+        """The file's mode as a string, e.g. '?rwxrwx---'"""
         # note we strip the mode because archive_entry_strmode
         # returns a trailing space: strcpy(bp, "?rwxrwxrwx ");
         return ffi.entry_strmode(self._entry_p).strip()

libarchive/write.py

@@ -191,6 +191,11 @@ def custom_writer(
     open_func=None, close_func=None, block_size=page_size,
     archive_write_class=ArchiveWrite, options='', passphrase=None,
 ):
+    """Create an archive and send it in chunks to the `write_func` function.
+
+    For formats and filters, see `WRITE_FORMATS` and `WRITE_FILTERS` in the
+    `libarchive.ffi` module.
+    """
 
     def write_cb_internal(archive_p, context, buffer_, length):
         data = cast(buffer_, POINTER(c_char * length))[0]
@@ -213,6 +218,11 @@ def fd_writer(
     fd, format_name, filter_name=None,
     archive_write_class=ArchiveWrite, options='', passphrase=None,
 ):
+    """Create an archive and write it into a file descriptor.
+
+    For formats and filters, see `WRITE_FORMATS` and `WRITE_FILTERS` in the
+    `libarchive.ffi` module.
+    """
     with new_archive_write(format_name, filter_name, options,
                            passphrase) as archive_p:
         ffi.write_open_fd(archive_p, fd)
@@ -224,6 +234,11 @@ def file_writer(
     filepath, format_name, filter_name=None,
     archive_write_class=ArchiveWrite, options='', passphrase=None,
 ):
+    """Create an archive and write it into a file.
+
+    For formats and filters, see `WRITE_FORMATS` and `WRITE_FILTERS` in the
+    `libarchive.ffi` module.
+    """
     with new_archive_write(format_name, filter_name, options,
                            passphrase) as archive_p:
         ffi.write_open_filename_w(archive_p, filepath)
@@ -235,6 +250,11 @@ def memory_writer(
     buf, format_name, filter_name=None,
     archive_write_class=ArchiveWrite, options='', passphrase=None,
 ):
+    """Create an archive and write it into a buffer.
+
+    For formats and filters, see `WRITE_FORMATS` and `WRITE_FILTERS` in the
+    `libarchive.ffi` module.
+    """
     with new_archive_write(format_name, filter_name, options,
                            passphrase) as archive_p:
         used = byref(c_size_t())