From eaf8f6085eafccad1741f402165ef90dd7b7ca6d Mon Sep 17 00:00:00 2001
From: Georg Pfuetzenreuter <mail@georg-pfuetzenreuter.net>
Date: Fri, 20 Sep 2024 19:00:54 +0200
Subject: [PATCH] Add proper README

Signed-off-by: Georg Pfuetzenreuter <mail@georg-pfuetzenreuter.net>
---
 README.md  | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.txt |  1 -
 2 files changed, 77 insertions(+), 1 deletion(-)
 create mode 100644 README.md
 delete mode 100644 README.txt

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b48214b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,77 @@
+# pyacl
+
+## Overview
+
+This is a high level abstraction over the great [pylibacl](https://pylibacl.k1024.org/) library.
+It removes the need for low level understanding of POSIX.1e by providing an interface similar to what one is used to by common ACL handling tools such as `getfacl(1)` and `setfacl(1)`. Handling of ACLs in `pyacl` happens through a map resembling what one would find as a result of calling `getfacl(1)`.
+
+## Example
+
+### Reading the ACL of a path
+
+The following shows a file at `/tmp/testacl1` on which an ACL granting the user `georg2` read permissions was applied.
+
+#### Result from `getfacl(1)`:
+
+```
+$ getfacl -c /tmp/testacl1
+getfacl: Removing leading '/' from absolute path names
+user::---
+user:georg2:r--
+group::r--
+mask::r--
+other::---
+```
+
+#### Result from `pyacl`:
+
+```
+>>> from pyacl import acl
+>>> acl.parse_acl_from_path('/tmp/testacl1')
+{'user': {'georg2': {'read': True, 'write': False, 'execute': False}},
+ 'group': {None: {'read': True, 'write': False, 'execute': False}},
+ 'mask': {None: {'read': True, 'write': False, 'execute': False}},
+ 'other': {None: {'read': False, 'write': False, 'execute': False}}}
+```
+
+### Writing an ACL to a path
+
+The following will apply ACL granting the user `georg2` read permissions to a file at `/tmp/testacl2`.
+
+```
+echo hi > /tmp/testacl2
+```
+
+#### With `setfacl(1)`:
+
+```
+setfacl -m u:georg2:r /tmp/testacl2
+```
+
+#### With `pyacl`:
+
+```
+>>> from pyacl import acl
+>>> myacl = acl.build_acl(target_name='georg2', target_type='user', read=True, write=False, execute=False)
+>>> acl.apply_acl_to_path(myacl, '/tmp/testacl2')
+```
+
+Of course, the `build_acl()` call could be shortened by omitting default arguments.
+
+## Documentation
+
+The functions provided by `pyacl` are documented through docstrings. Find them in the source code, or by calling `help()` - example:
+
+```
+>>> from pyacl import acl
+>>> help(acl.build_acl)
+Help on function build_acl in module pyacl.acl:
+
+build_acl(target_name, target_type, read=False, write=False, execute=False)
+    Example usage: build_acl(target_name='georg2', target_type='user', read=True, write=False, execute=True)
+    Return: posix1e.ACL
+```
+
+## Hacking/Tests
+
+Functionality is tested through `pytest`. As it requires a certain test user to be present, easiest is to use the purpose-built container image. A wrapper is provided at `test.sh`.
diff --git a/README.txt b/README.txt
deleted file mode 100644
index 00d7bdd..0000000
--- a/README.txt
+++ /dev/null
@@ -1 +0,0 @@
-WIP