mamweb/docs/zkratky.rst

Zkratky aplikací ve zdrojácích
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

Ve zdrojácích (zejména různé ``models.py``, ``views.py`` ap.) používáme spoustu
modelů. Někdy je praktičtější / někdo preferuje importovat celou aplikaci jako
jedno jméno a používat modely bez explicitních importů, tj::

    # „hromadné“ importy:
    import personalni.models as p
    ...
    p.Organizator.objects.all()

    # „explicitní“ importy:
    from personalni.models import Organizator
    ...
    Organizator.objects.all()

Na webschůzce 2024-11-05 jsme na toto téma otevřeli diskusi, tady je její závěr.

.. admonition:: Historické okénko
   :class: note

   Kdysi jsme měli (prakticky) všechny modely v jedné aplikaci, ``seminar``. Na
   různých místech se pak ``seminar.models`` importovalo typicky jako ``s``
   nebo jako ``m``.

   Přirozeně, toto už nejde tak snadno, protože už neexistuje jedno místo, ze
   kterého chceme tahat modely v kódu.

Konvence
========

Shodli jsme se, že nám rozhodně nevadí explicitní importy a z pohledu
čitelnosti je preferujeme. Nicméně při psaní kódu to některým webařům přijde
nepohodlné, takže očekáváme, že bude existovat spousta kódu, která bude chtít
importovat hromadně. Usnesli jsme se proto na následujících kanonických
zkratkách, aby se aplikace alespoň zkracovaly konzistentně.

V závorkách je uvedené případné jméno, ale nepředpokládáme, že někdo bude danou
aplikaci chtít importovat hromadně. Některé aplikace zkratku nemají, ty se
importují vždy pod plným jménem nebo explicitně.

.. list-table::
   :header-rows: 1

   * - Model
     - Zkratka
   * - ``aesop``
     - ---
   * - ``api``
     - --- (``api``)
   * - ``galerie``
     - ``g``
   * - ``header_fotky``
     - --- (``hdr``)
   * - ``korektury``
     - ``kor``
   * - ``novinky``
     - ``nov``
   * - ``odevzdavatko``
     - ``odev``
   * - ``personální``
     - ``pers``/``p``
   * - ``sifrovacka``
     - (``sifr``)
   * - ``soustredeni``
     - ``sou``
   * - ``treenode``
     - ``tn``
   * - ``tvorba``
     - ``tv``
   * - ``various``
     - ``v``/``var``
   * - ``vyroci``
     - ---
   * - ``vysledkovky``
     - ``vysl``


.. admonition:: O všech modelech pod jedním jménem
   :class: warning

   Historické okénko výš zatajuje jeden detail: Při práci v shellu se hodí mít
   modely k dispozici a nemuset přemýšlet nad dělením do aplikací, takže ve
   skutečnosti existuje ``mamweb.vsechno``, jenž všechny modely obsahuje.
   Z čitelnostních důvodů je ale *zakázáno* tento modul používat v kódu.