olski.python

Moduł wchodzi, polska proza wychodzi.

Repozytorium pisze o sobie nie tylko w dokumentach: docstring i blok komentarza są prozą, którą reguły pisania obejmują tak samo, a przybywa jej przy każdej zmianie w kodzie, bo prozę i nazwy bierzemy po polsku. Nad dokumentem sprowadza tę prozę pod olski-check olski/markdown.py; nad modułem sprowadza ją ten krok, więc olski-check olski/parse/las.py mówi o docstringu to samo, co o akapicie dokumentu.

Dwie decyzje przechodzą przez cały moduł i warto je powiedzieć raz.

Jednostką jest docstring albo blok komentarza, a nie plik. Moduł miesza polszczyznę z angielszczyzną z założenia: słowa kluczowe, klucze i API bibliotek zostają po angielsku, a sekcja napisana wcześniej zostaje taka, jaka jest, bo regułę językową przyjmujemy leniwie. Udział diakrytyków liczony nad całym plikiem nie ma więc nad czym stanąć i liczy się go nad jednostką (polish_share w harness/__init__.py).

Wiersze akapitu sklejają się w jeden, tak jak w Markdownie. Powód jest tu inny: pliku źródłowego nikt nie składa, więc złamanie wiersza w komentarzu jest albo zawijaniem na kolumnie, albo łamaniem semantycznym, a żadne z nich nie jest tym, co czytelnik widzi jako koniec wiersza.

Znaczniki reST czyta tu wzorzec, a nie parser, i tym ten krok różni się od tego nad Markdownem. Cenę tej różnicy trzyma docs/extraction.md, razem z rachunkiem z tego, co jeden i drugi po drodze zmyśla.

PYTHON_SUFFIX = '.py' module-attribute

POZYCJA = re.compile('[ \\t]*(?:[-*+]|\\d{1,9}[.)])[ \\t]+') module-attribute

ZNACZNIK = re.compile('#:?') module-attribute

WSTAWKI = re.compile('\n (?P<odstęp>[ \\t]*)\n (?:\n :\\w+:`(?P<rola>[^`]*)`\n | ``(?P<dosłownie>[^`]*)``\n | `(?P<kod>[^`]*)`\n | \\*\\*(?P<mocno>\\S(?:.*?\\S)??)\\*\\*\n )\n ', re.VERBOSE) module-attribute

GRUPY_WSTAWEK = ('rola', 'dosłownie', 'kod', 'mocno') module-attribute

ZAPOWIEDŹ = re.compile('(?P<odstęp>[ \\t]*)::\\Z') module-attribute

DOKUMENTOWANE = (ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef) module-attribute

proza(źródło)

Proza modułu, akapit w wierszu, w kolejności, w jakiej stoi w pliku.

Puste wiersze rozdzielają akapity, tak jak po drugiej stronie (olski.markdown.prose), więc zdanie nie przechodzi z jednego docstringa w następny.

Source code in olski/python.py

def proza(źródło: str) -> str:
    """Proza modułu, akapit w wierszu, w kolejności, w jakiej stoi w pliku.

    Puste wiersze rozdzielają akapity, tak jak po drugiej stronie
    (:func:`olski.markdown.prose`), więc zdanie nie przechodzi z jednego
    docstringa w następny.
    """
    ciało = "\n\n".join(tekst for _, tekst in jednostki(źródło))
    return ciało + "\n" if ciało else ""

jednostki(źródło)

Każdy docstring i każdy blok komentarza, po kolei, puste pominięte.

Wiersz idzie przed prozą, bo po ekstrakcji nie ma z czego go odtworzyć: w prozie modułu nie ma już kodu, który stał między jedną jednostką a drugą. Pytający robi z tej pary jednostkę wyboru po języku (harness.Jednostka), a wybór ten należy do harnessu, bo waży go ten, kto składa korpus, a nie ten, kto sprawdza swój plik.

Source code in olski/python.py

def jednostki(źródło: str) -> list[tuple[int, str]]:
    """Każdy docstring i każdy blok komentarza, po kolei, puste pominięte.

    Wiersz idzie przed prozą, bo po ekstrakcji nie ma z czego go odtworzyć: w
    prozie modułu nie ma już kodu, który stał między jedną jednostką a drugą.
    Pytający robi z tej pary jednostkę wyboru po języku
    (:class:`harness.Jednostka`), a wybór ten należy do harnessu, bo waży go ten,
    kto składa korpus, a nie ten, kto sprawdza swój plik.
    """
    znalezione = [*_docstringi(źródło), *_komentarze(źródło)]
    return sorted(((wiersz, tekst) for wiersz, tekst in znalezione if tekst), key=lambda j: j[0])