# WebUntis-Fetcher
WebUntis is a school-targeted communication platform by a company from Austria. I'm neither
affiliated to nor paid by them, but both the school my kids attend and the school my wife teaches
at use this platform, so I wanted to make looking at the class schedule as easy as possible.
*Caution: This project is modeled after the web application (by reverse engineering) and does
**not** use a publicly documented and stable API. So it can break at any time -
whenever Untis decides to change their backend.*
## First main function: timetable
This project can generate a timetable for multiple students and/or teachers in parallel,
which then can be uploaded or directly displayed somewhere. The result is a HTML file,
here's an example (orange = as planned, violet = changed, grey = cancelled, yellow = test):
In grey text below the tables, there are statistics about changed and cancelled lessons.
In this example, the data collection was started in October 2024.
## Second main function: messages
WebUntis allows the schools to send messages to the parents. They can have attachments,
and sometimes they have to be acknowledged. WebUntis can notify the users by email that
they have a message, but doesn't send the content - for that, you have to open their mobile
app or the web app - which can be tiresome if you have multiple accounts to check.
This project can be configured to fetch the messages from any number of accounts,
including any attachments, and send everything as email. And if a confirmation is
required, it is given automatically when sending the mail.
## Installation
You can choose one of these installation methods. For a later upgrade see below.
### From PyPI
1. Make sure that at least Python 3.9 is installed.
2. Optionally can now set up a [venv](https://docs.python.org/3/library/venv.html) and install
everything inside it (recommended). For creating it, execute `python3 -m venv venv`, and
afterwards activate it by executing `source venv/bin/activate`.
The following stays the same, you just have to remember to activate the venv before
using webuntis-fetcher later.
3. Execute `pip3 install webuntis-fetcher` to install the package including its dependencies.
### Manually
1. Clone [this project](https://github.com/mathisdt/webuntis-fetcher.git) to your computer,
or download the repository content as
[ZIP file](https://github.com/mathisdt/webuntis-fetcher/archive/refs/heads/master.zip).
2. Make sure that at least Python 3.9 is installed.
3. Optionally can now set up a [venv](https://docs.python.org/3/library/venv.html) and install
everything inside it (recommended). For creating it, execute `python3 -m venv venv`, and
afterwards activate it by executing `source venv/bin/activate`.
The following steps stay the same, you just have to remember to activate the venv before
using webuntis-fetcher later.
4. Install the package including its dependencies. If you want to be able to do a `git pull`
later and not have to re-install it, execute `pip3 install -e .`.
If you don't care about that possibility, use `pip3 install .`.
5. Test your installation by executing `webuntis-fetcher`. An error message should be written
to stderr pointing out that no mode was selected.
## Usage
### Fetch timetable
To configure the mode "timetable", copy
[config-template.ini](https://raw.githubusercontent.com/mathisdt/webuntis-fetcher/refs/heads/master/config-template.ini)
to e.g. `config.ini` and edit it so it contains your data.
The section names (inside the `[]`) are used as titles for the time tables,
with the exception of `[OUTPUT]` which can contain `timetable_file` - this defines the target
location of the generated timetable. Each other section can contain the following entries.
- The `server` field has to be set to whatever your school uses. You can see the server
name in the browser address bar when you are logged in, it's everything up to the first `/`.
- The `school` field has to contain whatever Untis calls the school. You can look it up
by logging into your WebUntis account in a web browser and click the RSS icon on the
"Today" page (small, orange). The link you're directed to contains the right name
(look at the address bar of the browser).
- The `class` field is not used to access the backend, but setting it (to any value)
switches to "student" mode. If `class` is unset, the "teacher" mode is used, and class
names are displayed next to the period subjects.
- `firstname` and `lastname` are used to look up the person for which the time table should
be displayed. This way you can use a parent login (which potentially has access to multiple
children's time tables) and still determine what should be displayed.
- `teacher_fullname_function` can be set to the name of a function which returns a dict
and is called only once per run - the result is used to result teacher names to
their full names because sometimes the "names" in Webuntis are only abbreviations.
For an example, see `kks_kannover_teachers` in the code.
- `statistics_file` can optionally point to a writable location of a XLSX file. Is does not
have to exist yet but it will be created if given. The content of this file will be
preserved over the weeks, and new data will be appended on the first sheet. The overall
statistics on the second sheet will be updated accordingly.
Now you can run `webuntis-fetcher timetable` periodically, which will write the output to
stdout - or provide a target filename via the config file. Any log messages will go to
stderr. Remember to activate the venv before (if you used one while installing).
You also can add another argument pointing to the location of your config file
if it's not `config.ini` in your current working directory.
### Fetch messages
To configure the mode "messages", copy
[config-template.ini](https://raw.githubusercontent.com/mathisdt/webuntis-fetcher/refs/heads/master/config-template.ini)
to e.g. `config.ini` and edit it so it contains your data.
The section names (inside the `[]`) are used as titles for the time tables,
with the exception of `[OUTPUT]` which is irrelevant here. As we're fetching messages,
it would make sense to include every login only once, even if if is used for muliple students.
- The `server` field has to be set to whatever your school uses. You can see the server
name in the browser address bar when you are logged in, it's everything up to the first `/`.
- The `school` field has to contain whatever Untis calls the school. You can look it up
by logging into your WebUntis account in a web browser and click the RSS icon on the
"Today" page (small, orange). The link you're directed to contains the right name
(look at the address bar of the browser).
- `message_id_file` should point to any writable file name. It does not have
to exist. In this file the IDs of handled messages are stored so you are not notified
multiple times for the same message.
- `mail_from`, `mail_to` and `mail_host` are self-explanatory. `mail_to` can contain
multiple addresses separated by a comma.
Now you can run `webuntis-fetcher messages` periodically, which will will send emails as
configured. Any log messages will go to stderr. Remember to activate the venv before
(if you used one while installing). You also can add another argument pointing to the
location of your config file if it's not `config.ini` in your current working directory.
## Upgrading
Remember to activate your venv beforehand if you use one!
If you chose the PyPI installation, upgrading is easy. Just execute
`pip3 install --upgrade webuntis-fetcher` and you're done.
If you installed manually and used `-e` on `pip3 install`, then it's also not hard: just
execute `git pull`. But even if you didn't, it's not much harder: First do `git pull`
and then another `pip3 install .`.
Raw data
{
"_id": null,
"home_page": null,
"name": "webuntis-fetcher",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "webuntis, untis, school, timetable, message, lesson, period",
"author": null,
"author_email": "Mathis Dirksen-Thedens <mail@zephyrsoft.org>",
"download_url": "https://files.pythonhosted.org/packages/a6/ad/763a3805a29aeb4086e4750a133d6f5a451fa65f6d2ab1c7ff038fa3fc54/webuntis_fetcher-4.tar.gz",
"platform": null,
"description": "# WebUntis-Fetcher\n\nWebUntis is a school-targeted communication platform by a company from Austria. I'm neither\naffiliated to nor paid by them, but both the school my kids attend and the school my wife teaches\nat use this platform, so I wanted to make looking at the class schedule as easy as possible.\n\n*Caution: This project is modeled after the web application (by reverse engineering) and does\n**not** use a publicly documented and stable API. So it can break at any time - \nwhenever Untis decides to change their backend.*\n\n## First main function: timetable\n\nThis project can generate a timetable for multiple students and/or teachers in parallel,\nwhich then can be uploaded or directly displayed somewhere. The result is a HTML file,\nhere's an example (orange = as planned, violet = changed, grey = cancelled, yellow = test):\n\n\n\nIn grey text below the tables, there are statistics about changed and cancelled lessons.\nIn this example, the data collection was started in October 2024.\n\n## Second main function: messages\n\nWebUntis allows the schools to send messages to the parents. They can have attachments,\nand sometimes they have to be acknowledged. WebUntis can notify the users by email that\nthey have a message, but doesn't send the content - for that, you have to open their mobile\napp or the web app - which can be tiresome if you have multiple accounts to check.\n\nThis project can be configured to fetch the messages from any number of accounts,\nincluding any attachments, and send everything as email. And if a confirmation is\nrequired, it is given automatically when sending the mail.\n\n## Installation\n\nYou can choose one of these installation methods. For a later upgrade see below.\n\n### From PyPI\n\n1. Make sure that at least Python 3.9 is installed.\n2. Optionally can now set up a [venv](https://docs.python.org/3/library/venv.html) and install\n everything inside it (recommended). For creating it, execute `python3 -m venv venv`, and\n afterwards activate it by executing `source venv/bin/activate`. \n The following stays the same, you just have to remember to activate the venv before \n using webuntis-fetcher later.\n3. Execute `pip3 install webuntis-fetcher` to install the package including its dependencies.\n\n### Manually\n\n1. Clone [this project](https://github.com/mathisdt/webuntis-fetcher.git) to your computer,\n or download the repository content as\n [ZIP file](https://github.com/mathisdt/webuntis-fetcher/archive/refs/heads/master.zip). \n2. Make sure that at least Python 3.9 is installed.\n3. Optionally can now set up a [venv](https://docs.python.org/3/library/venv.html) and install\n everything inside it (recommended). For creating it, execute `python3 -m venv venv`, and\n afterwards activate it by executing `source venv/bin/activate`. \n The following steps stay the same, you just have to remember to activate the venv before \n using webuntis-fetcher later.\n4. Install the package including its dependencies. If you want to be able to do a `git pull`\n later and not have to re-install it, execute `pip3 install -e .`.\n If you don't care about that possibility, use `pip3 install .`.\n5. Test your installation by executing `webuntis-fetcher`. An error message should be written\n to stderr pointing out that no mode was selected.\n\n## Usage\n\n### Fetch timetable\n\nTo configure the mode \"timetable\", copy \n[config-template.ini](https://raw.githubusercontent.com/mathisdt/webuntis-fetcher/refs/heads/master/config-template.ini)\nto e.g. `config.ini` and edit it so it contains your data.\n\nThe section names (inside the `[]`) are used as titles for the time tables,\nwith the exception of `[OUTPUT]` which can contain `timetable_file` - this defines the target\nlocation of the generated timetable. Each other section can contain the following entries.\n\n- The `server` field has to be set to whatever your school uses. You can see the server\n name in the browser address bar when you are logged in, it's everything up to the first `/`. \n- The `school` field has to contain whatever Untis calls the school. You can look it up\n by logging into your WebUntis account in a web browser and click the RSS icon on the\n \"Today\" page (small, orange). The link you're directed to contains the right name\n (look at the address bar of the browser).\n- The `class` field is not used to access the backend, but setting it (to any value)\n switches to \"student\" mode. If `class` is unset, the \"teacher\" mode is used, and class\n names are displayed next to the period subjects.\n- `firstname` and `lastname` are used to look up the person for which the time table should\n be displayed. This way you can use a parent login (which potentially has access to multiple\n children's time tables) and still determine what should be displayed.\n- `teacher_fullname_function` can be set to the name of a function which returns a dict\n and is called only once per run - the result is used to result teacher names to\n their full names because sometimes the \"names\" in Webuntis are only abbreviations.\n For an example, see `kks_kannover_teachers` in the code.\n- `statistics_file` can optionally point to a writable location of a XLSX file. Is does not \n have to exist yet but it will be created if given. The content of this file will be\n preserved over the weeks, and new data will be appended on the first sheet. The overall\n statistics on the second sheet will be updated accordingly.\n\nNow you can run `webuntis-fetcher timetable` periodically, which will write the output to\nstdout - or provide a target filename via the config file. Any log messages will go to\nstderr. Remember to activate the venv before (if you used one while installing).\nYou also can add another argument pointing to the location of your config file\nif it's not `config.ini` in your current working directory.\n\n### Fetch messages\n\nTo configure the mode \"messages\", copy \n[config-template.ini](https://raw.githubusercontent.com/mathisdt/webuntis-fetcher/refs/heads/master/config-template.ini)\nto e.g. `config.ini` and edit it so it contains your data.\n\nThe section names (inside the `[]`) are used as titles for the time tables,\nwith the exception of `[OUTPUT]` which is irrelevant here. As we're fetching messages,\nit would make sense to include every login only once, even if if is used for muliple students.\n\n- The `server` field has to be set to whatever your school uses. You can see the server\n name in the browser address bar when you are logged in, it's everything up to the first `/`. \n- The `school` field has to contain whatever Untis calls the school. You can look it up\n by logging into your WebUntis account in a web browser and click the RSS icon on the\n \"Today\" page (small, orange). The link you're directed to contains the right name\n (look at the address bar of the browser).\n- `message_id_file` should point to any writable file name. It does not have\n to exist. In this file the IDs of handled messages are stored so you are not notified\n multiple times for the same message.\n- `mail_from`, `mail_to` and `mail_host` are self-explanatory. `mail_to` can contain\n multiple addresses separated by a comma.\n\nNow you can run `webuntis-fetcher messages` periodically, which will will send emails as\nconfigured. Any log messages will go to stderr. Remember to activate the venv before\n(if you used one while installing). You also can add another argument pointing to the\nlocation of your config file if it's not `config.ini` in your current working directory.\n\n## Upgrading\n\nRemember to activate your venv beforehand if you use one!\n\nIf you chose the PyPI installation, upgrading is easy. Just execute\n`pip3 install --upgrade webuntis-fetcher` and you're done.\n\nIf you installed manually and used `-e` on `pip3 install`, then it's also not hard: just\nexecute `git pull`. But even if you didn't, it's not much harder: First do `git pull`\nand then another `pip3 install .`.\n",
"bugtrack_url": null,
"license": null,
"summary": "get school timetable data and messages from WebUntis",
"version": "4",
"project_urls": {
"Homepage": "https://github.com/mathisdt/webuntis-fetcher",
"Issues": "https://github.com/mathisdt/webuntis-fetcher/issues"
},
"split_keywords": [
"webuntis",
" untis",
" school",
" timetable",
" message",
" lesson",
" period"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f25b8f27f0c5c82a685b3dcd6d3461234330127e3494b5ccd873515e7074c7d2",
"md5": "19c82963c85091dc822ebc466c70ca4f",
"sha256": "9544f84c007d9808902702f143670fb5413fb8864e79bf2c004eea23a72f2b66"
},
"downloads": -1,
"filename": "webuntis_fetcher-4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "19c82963c85091dc822ebc466c70ca4f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 26335,
"upload_time": "2025-02-15T16:17:27",
"upload_time_iso_8601": "2025-02-15T16:17:27.258797Z",
"url": "https://files.pythonhosted.org/packages/f2/5b/8f27f0c5c82a685b3dcd6d3461234330127e3494b5ccd873515e7074c7d2/webuntis_fetcher-4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a6ad763a3805a29aeb4086e4750a133d6f5a451fa65f6d2ab1c7ff038fa3fc54",
"md5": "8660c096fca3b79e27c1d69ff56316e9",
"sha256": "fb4f5e2128914f98c91f12fd1a889be2f578f34fb77af193a4c31524b022eb30"
},
"downloads": -1,
"filename": "webuntis_fetcher-4.tar.gz",
"has_sig": false,
"md5_digest": "8660c096fca3b79e27c1d69ff56316e9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 27948,
"upload_time": "2025-02-15T16:17:29",
"upload_time_iso_8601": "2025-02-15T16:17:29.625413Z",
"url": "https://files.pythonhosted.org/packages/a6/ad/763a3805a29aeb4086e4750a133d6f5a451fa65f6d2ab1c7ff038fa3fc54/webuntis_fetcher-4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-15 16:17:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mathisdt",
"github_project": "webuntis-fetcher",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "webuntis-fetcher"
}
JSON
