Skip to main content

Bakaláři API v3 client

Project description

Bakaláři API v3 client

Baka(láři)
   API
------
Bakapi

Jednoduchý klient k API Bakalářů pro Python.

Changelog

0.3 (2020-10-27)

  • Nyní jsou defaultně používané timezone-aware datetimes. Pokud je token_valid_until timezone-unaware, předpokládá se že je v UTC.

  • Přidán volitelný parametr to k domácím úkolům, viz změny v API dokumentaci

0.2 (2020-10-13)

  • Umožnění vytvoření klienta bez hesla, pouze z refresh_tokenu, případně spolu s access_tokenem a jeho platností.

  • Přidán volitelný parametr since k domácím úkolům. Když není zadán, tak Bakaláři vrátí jen úkoly z posledních dvou měsíců (viz API dokumentace)

0.1 (2020-04-09)

První release

Dokumentace

The code is the documentation. (Pls naučte mě někdo Sphinx)

Modul obsahuje hlavní třídu BakapiUser.

Konstruktor vždy vyžaduje dva keyword argumenty: url a username. Dále vyžaduje buď password, které je okamžitě použito k získání access_tokenu, nebo refresh_token, volitelně spolu s access_token a token_valid_until. Ty jsou uloženy a token je v případě potřeby obnoven až při prvním API požadavku.

Metody instancí BakapiUser

send_request(endpoint, method="GET", **kwargs) zkontroluje platnost access_tokenu, případně ho obnoví. Poté pošle požadavek s autorizačním headrem. kwargs jsou předány metodě requests.request.
Vrací requests.Response

query_api(endpoint, method="GET", **kwargs) volá send_request, pouze navíc ověřuje, že dostala validní JSON odpověď.
Vrací naparsovaná data jako dict

get_user_info() získá informace o uživateli, vrací dict tak, jak ho dostane od Bakalářů. Vypadá zhruba takto:

{'UserUID': '...',
 'Class': <trida>,
 'FullName': '...',
 'SchoolOrganizationName': '...',
 'SchoolType': None,
 'UserType': 'student',
 'UserTypeText': 'žák',
 'StudyYear': 1,
 'EnabledModules': [
    {'Module': '<nazev modulu>', 'Rights': ['...']}
  ],
 'SettingModules': {'...?'}
}

Známé názvy modulů:
Komens, Absence, Events, Marks, Timetable, Substitutions, Subjects, Homeworks, Gdpr

Třída je jednoduchý dict, vypadá takto:

{'Id': '...', 'Abbrev': '...', 'Name': '...'}

get_homework() získá seznam všech úkolů, vrací dict tak, jak ho dostane od Bakalářů. Přijímá volitelný parametr since, kterým lze omezit datum, od kterého jsou brané úkoly. Může být datetime.date, datetime.datetime nebo "YYYY-MM-DD". Odpověď vypadá takto:

{"Homeworks": [
    <ukoly>
  ]
}

Každý úkol vypadá zhruba takto:

{'ID': '...',
 'DateAward': '0001-01-01T00:00:00+01:00',
 'DateControl': None,
 'DateDone': '0001-01-01T00:00:00+01:00',
 'DateStart': '0001-01-01T00:00:00+01:00',
 'DateEnd': '0001-01-01T00:00:00+01:00',
 'Content': '...',
 'Notice': '',
 'Done': True,
 'Closed': True,
 'Electronic': False,
 'Hour': 6,
 'Class': <trida>,
 'Group': <skupina>,
 'Subject': <predmet>,
 'Teacher': <ucitel>,
 'Attachments': [<prilohy>]}

Třída, skupina, předmět a učitel jsou jednoduchý dict, viz třída u get_user_info()

Každá příloha vypadá takto:

{'Id': '...',
     'Name': '...',
     'Type': 'mime/type'}

get_received_komens_messages() získá seznam všech přijatých zpráv v Komens, vrací dict tak, jak ho dostane od Bakalářů. Vypadá takto:

{"Messages": [
    <zpravy>
  ]
}

Každá zpráva vypadá zhruba takto:

{'$type': 'GeneralMessage',
 'Id': '...',
 'Title': 'Obecná zpráva',
 'Text': '...',
 'SentDate': '0001-01-01T00:00:00+01:00',
 'Sender': <odesilatel>,
 'Attachments': [<prilohy>],
 'Read': True,
 'LifeTime': 'ToRead',
 'DateFrom': None,
 'DateTo': None,
 'Confirmed': True,
 'CanConfirm': False,
 'Type': 'OBECNA',
 'CanAnswer': True,
 'Hidden': False,
 'CanHide': True,
 'RelevantName': '...',
 'RelevantPersonType': 'teacher|administrator|...?'}

Odesílatel je jednoduchý dict, viz třída u get_user_info()

Pro formát přílohy viz úkoly.

download_attachment(attachment_id) stáhne přílohu s daným ID.
Vrací dvojici filename, urllib3.response.HTTPResponse

Dokumentace endpointů je průběžně vytvářena v repozitáři bakalari-api/bakalari-api-v3

Ukázky

Použití přímo

>>> from bakapi import BakapiUser
>>> u = BakapiUser(url="https://bakalari.skola.cz", username="jan_novak", password="honzikovoHeslo")
>>> u.get_homework()
{'Homeworks': [
  {'ID': 'ABCDEFG',
   '...': '...',
   'Attachments': [
     {'Id': 'EFAAAAG',
      'Name': 'Ukol.doc',
      'Type': 'application/msword'}]
  },
  '...'
]}
>>> with open("Ukol.doc", "wb") as fh:
...   fh.write(u.download_attachment("EFAAAAG")[1].read())

Použití jako Mixin

Knihovnu lze také použít jako Mixin do vaší vlastní classy uživatele.

Pokud například chcete ve své aplikaci ukládat data do databáze pomocí SQLAlchemy, vytvořte classu uživatel takto:

class User(BakapiUser, DeclarativeBase):
    id = Column(Integer, primary_key=True, autoincrement=True)

    # API používá tyto properties:
    url = Column(String)
    username = Column(String)
    token_valid_until = Column(DateTime)
    refresh_token = Column(String)
    access_token = Column(String)

    # další data, která používá vaše aplikace
    more_data = Column(String)

u = User(
    url="https://bakalari.skola.cz",
    username="jan_novak",
    password="honzikovoHeslo",
    more_data="neco"
)
  • Je důležité, aby BakapiUser byl v seznamu inherited classes první, protože on předává nepotřebné init parametry. Ostatní classy to ale dělat nemusí (a právě např. DeclarativeBase to nedělá).
  • Nemusíte definovat metodu __init__, ale pokud ji definujete, musí volat super().__init__()
  • Konstruktor příjímá povinné keyword argumenty (viz začátek). Cokoliv dalšího pošle dál

Pro pochopení doporučuji tuto StackOverflow answer

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for bakapi, version 0.3
Filename, size File type Python version Upload date Hashes
Filename, size bakapi-0.3-py3-none-any.whl (6.8 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size bakapi-0.3.tar.gz (6.7 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page