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.

Dokumentace

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

Modul obsahuje hlavní třídu BakapiUser.

Konstruktor vyžaduje tři keyword argumenty: url, username a password. Tyto využije k získání prvního access_tokenu a refresh_tokenu.

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ářů. 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").content)

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á tři povinné keyword argumenty – url, username, password. 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.

Source Distribution

bakapi-0.1.tar.gz (5.5 kB view hashes)

Uploaded Source

Built Distribution

bakapi-0.1-py3-none-any.whl (5.7 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page