Skip to content

Latest commit

 

History

History
66 lines (38 loc) · 3.37 KB

README.md

File metadata and controls

66 lines (38 loc) · 3.37 KB
Raw

GimVičUrnik

An API for a school timetable, substitutions and menus at Gimnazija Vič.

Description

This is the API part of the GimVičUrnik system. For more details see the main README file.

Installation

GimVičUrnik API requires Python 3.10 or later, and Poetry dependency manager with the poetry-dynamic-versioning plugin.

You can clone this repository and install it using Poetry:

git clone https://github.com/filips123/GimVicUrnik.git
cd GimVicUrnik/API
poetry install

This will download and install all required dependencies and add gimvicurnik as command. Depending on your Poetry configuration, you might need to activate its virtual environment to use the command.

You will also need to install one of SQLAlchemy dialects to use databases other than SQLite. The mysql-py (pymysql), mysql-c (mysqlclient) and pgsql (psycopg2) dialects are already specified as package extras. Optional Sentry is available as a sentry extra.

Usage

Configuration

GimVičUrnik API uses YAML file for configuration. Example file can be found at config.yaml.sample. You can also see default values and the schema in the source code. If you don't plan to use Sentry, you can delete its section entirely. Logging section will by default display INFO or higher log levels to stdout, but you can also delete or change it if you don't want that.

You need to obtain the e-classroom token as specified in the Moodle Forum Discussion.

It is recommended to set the configuration file as GIMVICURNIK_CONFIG environment variable, but setting --config argument also mostly works.

Preparation

You need to run gimvicurnik create-database to create all required database tables before running other commands or the server.

Fetching Data

Data need to be fetched and updated in separate commands from the web server. Most likely you want to execute them periodically in a cron job.

  • gimvicurnik update-timetable: Update the timetable data
  • gimvicurnik update-eclassroom: Update the e-classroom data (substitutions, lunch schedule, circulars)
  • gimvicurnik update-menu: Update the menu data (snack and lunch menu)

Starting Server

The development server can be started with gimvicurnik run. It is based on the default Flask's built-in server and will respect all of its environment variables (except FLASK_APP, which is configured automatically).

In production, you should use any WSGI-compatible server. See Flask Documentation for more details. GimVičUrnik API uses the app factory located at gimvicurnik.create_app to create the application.

Using the API

You can retrieve all API routes using the gimvicurnik routes commands. The official client can be found in the website directory.

Contributing

The API uses ruff, black and mypy for linting the code. They are included in project's development dependencies.

Please make sure that your changes are formatted correctly according to the code style:

  • Linting: ruff gimvicurnik
  • Typechecking: mypy gimvicurnik
  • Formatting: black gimvicurnik