update readme and documentation

README.md

@@ -1,3 +1,40 @@
 # asscryption
 
-i demand a gist service rn
+Proof-of-concept random key-based text transformer.
+
+## Usage
+
+### Encrypt
+
+```sh
+python main.py encrypt <filein> <target> [--seed SEED] > keyfile
+```
+
+- `filein`: Input text file (plaintext)
+- `target`: Target text file (what you want to transform to)
+- `--seed`: (Optional) Random seed for reproducibility
+- `keyfile`: Output key file (redirect stdout)
+
+### Decrypt
+
+```sh
+python main.py decrypt <filein> <keyfile>
+```
+
+- `filein`: Input text file (should match the input used in encrypt)
+- `keyfile`: Key file produced during encryption
+
+### Example
+
+```sh
+python main.py encrypt message.txt target.txt --seed 42 > mykey.txt
+python main.py decrypt message.txt mykey.txt > reconstructed_target.txt
+```
+
+---
+
+**NOTE:** This is a proof-of-concept. The "key" is printed to stdout during encryption. The target file must exist.
+
+---
+
+Version 1

main.py

@@ -25,9 +25,16 @@ from itertools import repeat
 import random
 import argparse
 from typing import Generator, Tuple
+import ast
 
 
 def index_list(range: range, length: int, seed=None) -> Generator[int, None, None]:
+    """
+    Generate a sequence of random indices from the given range, of specified length.
+    If a seed is provided, the random sequence is reproducible.
+    Yields:
+        random_index: int: Randomly chosen index from the range.
+    """
     if seed is not None:
         random.seed(seed)
     return (random.choice(range) for _ in repeat(None, length))
@@ -36,6 +43,13 @@ def index_list(range: range, length: int, seed=None) -> Generator[int, None, Non
 def funky_function(
     text_in, text_out, seed=None
 ) -> Generator[Tuple[int, int], None, None]:
+    """
+    For each character in text_out, randomly select a character from text_in (using index_list),
+    and yield a tuple (index_in, offset) where offset is the difference in ordinal values.
+    This forms the 'key' for transforming text_in to text_out.
+    Yields:
+        (index_in, offset): Tuple[int, int]
+    """
     range_text_in = range(len(text_in))
     len_text_out = len(text_out)
     for id_out, id_in in enumerate(index_list(range_text_in, len_text_out, seed)):
@@ -45,6 +59,12 @@ def funky_function(
 
 
 def rebuild(text_in, this: Generator[Tuple[int, int], None, None]):
+    """
+    Rebuilds the output text by applying the offset to the character at index_in in text_in
+    for each (index_in, offset) in the key.
+    Yields:
+        str: The resulting character after transformation.
+    """
     for ind, offset in this:
         val_in = text_in[ind]
         yield chr(ord(val_in) + offset)
@@ -85,9 +105,8 @@ def main():
         # read filein, read keyfile, print recovered text
         with open(args.filein, "r", encoding="utf-8") as fin:
             text_in = fin.read()
-        with open(args.keyfile, "r", encoding="utf-8") as kf:
-            import ast
 
+        with open(args.keyfile, "r", encoding="utf-8") as kf:
             key = ast.literal_eval(kf.read())
 
         # Rebuild original text