docs and compatibility

Author: ckrause

README.md

@@ -1,10 +1,17 @@
-# LODA Python Module
+# LODA Python
 
-This Python module contains an implementation of the [LODA Language](https://loda-lang.org/). You can use it to read, write and evaluate LODA programs to integer sequences, and to use machine learning to find new programs.
+This Python package contains an implementation of the [LODA Language](https://loda-lang.org/):
+an assembly language and computational model for finding integer sequence programs.
+
+This Python package allows you to read and write LODA programs, to evaluate
+them to integer sequences, to search for matches in the
+[OEIS](https://www.oeis.org/) database,
+and to use machine learning tools from [Tensorflow](https://www.tensorflow.org/)
+to find new integer sequence programs.
 
 ## Getting Started
 
-Install the dependencies for the LODA Python module:
+You need Python 3.7 or higher. To install the dependencies for LODA, run these commands:
 
 ```bash
 python3 -m venv env
@@ -18,4 +25,4 @@ To execute the tests, run the following command:
 nose2 tests -v
 ```
 
-Check out [sample.py](sample.py) and the [documentation](https://loda-lang.org/loda-python/) to find out how to use the LODA Python module.
+Check out [sample.py](sample.py) and the [documentation](https://loda-lang.org/loda-python/) to find out how to use the LODA Python package.

fibonacci.asm

@@ -0,0 +1,9 @@
+; A000045: Fibonacci numbers.
+mov $3,1
+lpb $0
+  sub $0,1
+  mov $2,$1
+  add $1,$3
+  mov $3,$2
+lpe
+mov $0,$1

loda/__init__.py

@@ -1,9 +1,6 @@
-"""Python implementation of the [LODA Language](https://loda-lang.org/):
-an assembly language and computational model for finding integer sequence programs.
+"""
+Python implementation of the [LODA Language](https://loda-lang.org/):
+an assembly language and computational model for integer sequences.
 
-This Python package allows you to read and write LODA programs, to evaluate
-them to integer sequences, to search for matches in the
-[On-Line Encyclopedia of Integer Sequences®](https://www.oeis.org/) (OEIS®),
-and to use machine learning from [Tensorflow](https://www.tensorflow.org/)
-to find new integer sequence programs.
+.. include:: ./documentation.md
 """

loda/documentation.md

@@ -0,0 +1,42 @@
+This Python package allows you to read and write LODA programs, to evaluate
+them to integer sequences, to search for matches in the
+[OEIS](https://www.oeis.org/) database,
+and to use machine learning from [Tensorflow](https://www.tensorflow.org/)
+to generate new integer sequence programs.
+
+## Installation
+
+You need Python 3.7 or higher. To install the dependencies for LODA, run these commands:
+
+```bash
+python3 -m venv env
+source env/bin/activate
+pip install -r requirements.txt
+```
+
+## Getting Started
+
+LODA programs are stored in `*.asm` files. Below you can find the example program `fibonacci.asm` which
+computes the Fibonacci numbers. For a comprehensive overview of the language, see the [LODA Language Specification](https://loda-lang.org/spec/).
+
+```asm
+; A000045: Fibonacci numbers.
+mov $3,1
+lpb $0
+  sub $0,1
+  mov $2,$1
+  add $1,$3
+  mov $3,$2
+lpe
+mov $0,$1
+```
+
+Check out the [sub-modules](#header-submodules) for working with LODA programs.
+
+## Development
+
+To execute the tests, run the following command:
+
+```bash
+nose2 tests -v
+```

loda/lang/__init__.py

@@ -1,4 +1,18 @@
-"""LODA Language core. Model and (de-)serialization of programs.
+"""
+Load and save programs.
+
+This module contains the in-memory representation of LODA programs. You can use it to load and save programs,
+and to inspect and manipulate their structure programmatically. You can load a program from an `*.asm` file
+as follows:
+
+>>> from loda.lang import Program
+>>>
+>>> with open("fibonacci.asm", "r") as file:
+>>>     program = Program(file.read())
+>>>     print(program)
+
+To save it, just write the string representation of the program to another file.
+To inspect and manipulate programs, see the `loda.lang.program.Program` class.
 """
 
 from .operand import Operand

loda/lang/operand.py

@@ -1,11 +1,12 @@
 # -*- coding: utf-8 -*-
 
+"""Operand model and serialization."""
+
 from enum import Enum
 
 
 class Operand:
-    """Operand model and (de-)serialization.
-
+    """
     Operands consist of two members: `type` (enum) and `value` (int).
     The operand's type can be either `CONSTANT`, `DIRECT` memory access,
     or `INDIRECT` memory access. Constants are plain integers. Direct

loda/lang/operation.py

@@ -1,12 +1,13 @@
 # -*- coding: utf-8 -*-
 
+"""Operation model and serialization."""
+
 from enum import Enum
 from .operand import Operand
 
 
 class Operation:
-    """Operation model and (de-)serialization.
-
+    """
     Operations have the following structure: `<type> <target>,<source> ; <comment>`
     where the operation type is an enum consisting of three-letter operation names, and
     target and source are `loda.lang.operand.Operand`s. Depending on their type, 

loda/lang/program.py

@@ -1,10 +1,13 @@
 # -*- coding: utf-8 -*-
 
+"""Program model and serialization."""
+
 from .operation import Operation
 
 
 class Program:
-    """Program model and (de-)serialization.
+    """
+    Programs are essentially a list of `Operation`s.
 
     >>> # Constructing programs from operations:
     >>> p1 = Program()
@@ -21,7 +24,7 @@ class Program:
     div $0,$2
     """
 
-    operations: list[Operation]
+    operations: list
     """Operations of this program."""
 
     def __init__(self, program_str=None):

loda/ml/__init__.py

@@ -1 +1,3 @@
-"""Machine learning integration for LODA using Tensorflow/Keras."""
+"""
+Machine learning integration.
+"""

loda/ml/keras.py

@@ -9,7 +9,7 @@
 
 class Model(tf.keras.Model):
 
-    def __init__(self, vocabulary: list[str],
+    def __init__(self, vocabulary: list,
                  embedding_dim: int = 256, num_rnn_units: int = 1024):
 
         super().__init__(self)
@@ -75,10 +75,10 @@ def __init__(self, model: Model, temperature: float = 1.0):
             dense_shape=[model.get_vocab_size()])
         self.prediction_mask = tf.sparse.to_dense(sparse_mask)
 
-    def ids_to_tokens_str(self, ids) -> list[str]:
+    def ids_to_tokens_str(self, ids) -> list:
         return [t.numpy().decode("utf-8") for t in self.model.ids_to_tokens(ids)]
 
-    def ids_to_programs(self, ids) -> list[Program]:
+    def ids_to_programs(self, ids) -> list:
         return util.split_program(util.tokens_to_program(self.ids_to_tokens_str(ids)))
 
     def program_to_input_ids(self, program: Program, num_lanes: int = 1):