initial commit

1 files changed, 79 insertions, 0 deletions

diff --git a/Readme.md b/Readme.md
new file mode 100644
index 0000000..72451cf
--- /dev/null
+++ b/Readme.md
@@ -0,0 +1,79 @@
+# avail-lessons - Get all available lessons and possible school events from webuntis
+
+The `lessons.py` script can be used to retrieve a list of all future lessons in the school year for a specific class and subject from a webuntis server.
+
+I use the script to create sequence plans for the classes I teach.
+
+Because some lesson potentially get canceled because of school events the script supports reading events from ICS files (links and files are supported) and showing each event during one of the lessons.
+
+Example lessons starting from the current day (`2023-04-05`) using the default format:
+
+    $ ./lessons.py --class 6D --subject NuT-Inf --show-events
+    
+    16 18.04 Event1
+    17 25.04 Event2
+    18 02.05 Event2 & Event3
+    19 09.05 Event4 & Event5 & Event6
+    20 16.05 Event7 & Event8
+    21 23.05 Event7 & Event9
+    24 13.06 Event10 & Event11
+    25 20.06 Event12
+    26 27.06 Event12
+    27 04.07 Event13 & Event14
+    28 11.07
+    29 18.07
+    30 25.07
+
+You have do decide manually if an event is relevant for your planning.
+
+## Requirements
+
+The script requires [toml](https://pypi.org/project/toml/), [webuntis](https://pypi.org/project/webuntis/) and [icalendar](https://pypi.org/project/icalendar/) python packages and was written for python version 3.10.
+A pipenv file is included in the repository to install the required dependencies in a python 3.10 virtual environment.
+Run `pipenv install` to create a virtual environment containing all requirements.
+Afterwards, the virtual environment can be entered by running `pipenv shell`.
+Alternatively, the script can be run inside the virtual environment using `pipenv run -- ./lesson.py [options]`.
+
+## Configuration
+
+A simple [toml](https://toml.io/en/) configuration file is supported following the (XDG Base Directory Specification)[https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html].
+All command line options are supported in the configuration file.
+Additionally, an array of ICS calendar URIs can be specified with the `icalendars` key.
+A sample configuration file is included in the repository.
+
+## Usage
+
+To obtain a list of future lessons for an example (5A) math class run `./lessons.py --class 5A --subject M`.
+
+**Note**: the specified subject and class name must match the your webuntis conventions.
+
+    usage: lessons.py [-h] [--school SCHOOL] [--server SERVER] [--user USER] [--password PASSWORD]
+                      [--config CONFIG] [--teacher TEACHER] [--subject SUBJECT] [--class CLASS]
+                      [--show-events]
+    
+    options:
+      -h, --help           show this help message and exit
+      --school SCHOOL      The shool identifier used by webuntis
+      --server SERVER      The webuntis server
+      --user USER          The webuntis login username
+      --password PASSWORD  The webuntis login password
+      --config CONFIG      Path to a configuration file
+      --teacher TEACHER    The teacher abbreviation used in webuntis
+      --subject SUBJECT    The subject abbreviation used in webuntis
+      --class CLASS        The class name
+      --show-events        Show ICS calendar events during the lessons
+
+## License
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.