commit 5ab11217db07490ebf3c319e57b2a61c03522813
Author: TheOnePath <ethan.sc@closedless.xyz>
Date:   Wed Jun 7 19:48:58 2023 +0100

    Added README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..50b6d2a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,64 @@
+# ExtractAr
+A basic Python implementation of the Unix `ar` command which can extract files from a Debian binary package archive.
+
+ExtractAr is a rework of the `unix_ar` single Python module library by [remram44](https://github.com/remram44/unix_ar)
+but no longer supported and maintained. It is still a single module library, but with half the content; ExtractAr,
+meaning "Extract Archive" only reads and extracts files archived, not creating archives.
+
+As Python is cross-platform, making use of the standard library, it means archive files can be extracted on Windows or
+Linux systems. 
+
+# Usage
+The below code snippet is a basic example of how to use ExtractAr:
+
+```py
+import extractar 
+
+if __name__ == "__main__":
+    ar = extractar.Archive("/path/to/deb/file.deb")
+    ar.open() # load the archive into memory
+    
+    print("Extracting content from archive...")
+    ar.extractall()
+    
+    print("Archive extracted.")
+```
+
+However, ExtractAr employs strict handling of content through many stages of the reading and extraction process. It's
+possible that an I/O error occurs when dealing with reading the archive file. When extracting files, it's possible that
+the archive content is corrupt or not in the Debian binary package format. The following is a more robust method of
+operating with ExtractAr:
+
+```py
+import extractar 
+import sys
+
+if __name__ == "__main__":
+    ar = extractar.Archive("/path/to/deb/file.deb")
+
+    try:
+        ar.open() # load the archive into memory
+    except:
+        print("There was an issue when reading the archive file:", sys.exc_info()[0])
+    
+    print("Extracting content from archive...")
+
+    try:
+        ar.extractall()
+    except extractar.ArchiveMagicByteError:
+        print("Looks like the archive isn't of Debian binary package format.")
+    except extractar.ArchiveBufferReadError as err:
+        print("The archive might be corrupt. The following was raised when extracting files:", err)
+    except:
+        print("An issue occurred during archive extraction:", sys.exc_info()[0])
+    
+    print("Archive extracted.")
+```
+
+Code may not be required specific handling in this manner, but is an example of dealing with exceptions that may arise
+during the runtime of the file.
+
+# Licence
+The original source code was licence under Modified BSD licence, which has been acknowledged appropriately. For licence
+agreement on ExtractAr, see LICENCE.txt for licence agreement.
+