micropython — přístup k interním částem MicroPythonu a jejich řízení

Funkce

micropython.const(expr: int) → int

Slouží k deklaraci, že výraz je konstanta, aby jej kompilátor mohl optimalizovat. Tato funkce by se měla používat takto:

from micropython import const

CONST_X = const(123)
CONST_Y = const(2 * CONST_X + 1)

Takto deklarované konstanty jsou stále přístupné jako globální proměnné zvenčí modulu, ve kterém jsou deklarovány. Naopak pokud konstanta začíná podtržítkem, je skrytá, není dostupná jako globální proměnná a během běhu nezabírá žádnou paměť.

Tato funkce const je rozpoznávána přímo parserem MicroPythonu a je poskytována jako součást modulu micropython hlavně proto, aby bylo možné psát skripty běžící jak pod CPython, tak pod MicroPython, dodržováním výše uvedeného vzoru.

micropython.opt_level(level: int | None = None) → int | None

Pokud je zadáno level, nastaví tato funkce úroveň optimalizace pro následnou kompilaci skriptů a vrátí None. Jinak vrátí aktuální úroveň optimalizace.

Úroveň optimalizace řídí následující funkce kompilace:

• Aserce: na úrovni 0 jsou příkazy assert povoleny a kompilovány do bytecode; na úrovních 1 a vyšších se aserce nekompilují.

• Vestavěná proměnná __debug__: na úrovni 0 se tato proměnná rozvine na True; na úrovních 1 a vyšších se rozvine na False.

• Čísla řádků zdrojového kódu: na úrovních 0, 1 a 2 se čísla řádků zdrojového kódu ukládají spolu s bytecode, aby výjimky mohly hlásit číslo řádku, na kterém nastaly; na úrovních 3 a vyšších se čísla řádků neukládají.

Výchozí úroveň optimalizace je obvykle úroveň 0.

micropython.alloc_emergency_exception_buf(size: int) → None

Alokuje size bajtů RAM pro nouzový buffer výjimek (vhodná velikost je kolem 100 bajtů). Buffer slouží k vytváření výjimek v případech, kdy by normální alokace RAM selhala (např. uvnitř obslužné rutiny přerušení), a poskytuje tak v těchto situacích užitečné informace o traceback.

Dobrý způsob použití této funkce je umístit ji na začátek hlavního skriptu (např. boot.py nebo main.py), a nouzový buffer výjimek pak bude aktivní pro veškerý následující kód.

micropython.mem_info(verbose: Any | None = None) → None

Vypíše informace o aktuálně využívané paměti. Pokud je zadán argument verbose, vypíší se dodatečné informace.

Vypisované informace závisejí na implementaci, ale v současnosti zahrnují množství využitého zásobníku a haldy. Ve verbose režimu vypisuje celou haldu s vyznačením, které bloky jsou využity a které volné.

micropython.qstr_info(verbose: Any | None = None) → None

Vypíše informace o aktuálně internovaných řetězcích. Pokud je zadán argument verbose, vypíší se dodatečné informace.

Vypisované informace závisejí na implementaci, ale v současnosti zahrnují počet internovaných řetězců a množství RAM, které využívají. Ve verbose režimu vypisuje názvy všech řetězců internovaných v RAM.

micropython.stack_use() → int

Vrátí celé číslo představující aktuální množství využívaného zásobníku. Jeho absolutní hodnota není nijak zvlášť užitečná, spíše by se mělo používat k výpočtu rozdílů ve využití zásobníku v různých bodech.

micropython.heap_lock() → None

Zamkne haldu. Dokud je zamčená, nemůže dojít k žádné alokaci paměti a při pokusu o jakoukoli alokaci na haldě bude vyvolána výjimka MemoryError.

Zámky se vnořují: opakované volání heap_lock() zvyšuje hloubku zámku. Halda zůstane zamčená, dokud nebude heap_unlock() zavoláno stejněkrát.

Pokud se REPL stane aktivním se zamčenou haldou, bude halda násilně odemčena.

micropython.heap_unlock() → int

Sníží hloubku zámku haldy o jedničku a vrátí novou hloubku jako nezáporné celé číslo. Návratová hodnota 0 znamená, že halda již není zamčená a alokace jsou opět povoleny.

micropython.heap_locked() → int

Vrátí aktuální hloubku zámku haldy jako nezáporné celé číslo; 0 znamená, že halda není zamčená.

Poznámka: tato funkce není na OpenMV Cam dostupná.

micropython.kbd_intr(chr: int) → None

Nastaví znak, který vyvolá výjimku KeyboardInterrupt. Ve výchozím nastavení je tento znak během provádění skriptu nastaven na 3, což odpovídá Ctrl-C. Předání hodnoty -1 této funkci vypne zachytávání Ctrl-C a předání hodnoty 3 jej obnoví.

Tuto funkci lze použít k zabránění zachytávání Ctrl-C v příchozím proudu znaků, který se obvykle používá pro REPL, pro případ, že je tento proud využíván k jiným účelům.

micropython.schedule(func: Callable[[Any], Any], arg: Any) → None

Naplánuje funkci func k provedení „velmi brzy“. Funkci se předává hodnota arg jako její jediný argument. „Velmi brzy“ znamená, že běhové prostředí MicroPythonu udělá vše pro to, aby funkci provedlo v nejbližším možném okamžiku, vzhledem k tomu, že se zároveň snaží být efektivní a že platí následující podmínky:

• Naplánovaná funkce nikdy nepřeruší jinou naplánovanou funkci.

• Naplánované funkce se vždy provádějí „mezi opkódy“, což znamená, že všechny základní operace Pythonu (jako je přidání do seznamu) jsou zaručeně atomické.

• Konkrétní port může definovat „kritické oblasti“, v nichž se naplánované funkce nikdy neprovedou. Funkce lze v kritické oblasti naplánovat, ale neprovedou se, dokud se tato oblast neopustí. Příkladem kritické oblasti je přerušující obslužná rutina přerušení (IRQ).

• Uvnitř funkcí nativního kódu se naplánované funkce nevolají, ledaže nativní kód zavolá funkci, která to konkrétně udělá.

• Některé funkce včetně poll.poll, poll.ipoll, time.sleep a time.sleep_ms (včetně spánků nulové délky) naplánované funkce zavolají.

Použitím této funkce je naplánovat callback z přerušujícího IRQ. Takové IRQ klade omezení na kód běžící v IRQ (například může být zamčená halda) a naplánování funkce k pozdějšímu zavolání tato omezení zruší.

Na vícevláknových portech závisí chování naplánované funkce na tom, zda je pro konkrétní port povolen globální zámek interpretu (GIL):

• Pokud je GIL povolen, funkce může přerušit jakékoli vlákno a běžet v jeho kontextu.

• Pokud je GIL zakázán, funkce přeruší pouze hlavní vlákno a poběží v jeho kontextu.

Poznámka: Pokud je schedule() voláno z přerušujícího IRQ, kdy není povolena alokace paměti, a callback, který se má předat funkci schedule(), je vázaná metoda, přímé předání selže. Je to proto, že vytvoření odkazu na vázanou metodu způsobí alokaci paměti. Řešením je vytvořit odkaz na metodu v konstruktoru třídy a předat tento odkaz funkci schedule(). To je podrobně rozebráno zde referenční dokumentace v části „Creation of Python objects“.

Existuje konečná fronta pro uchovávání naplánovaných funkcí a schedule() vyvolá RuntimeError, pokud je fronta plná.

Třídy

class micropython.RingIO(size: int)

class micropython.RingIO(buffer: bytes | bytearray | memoryview)

Poskytuje kruhový buffer s pevnou velikostí pro bajty se stream rozhraním. Lze jej považovat za variantu FIFO fronty io.BytesIO. Obě formy konstruktoru se liší pouze v tom, jak je dodán podkladový buffer:

• RingIO(size) alokuje podkladový buffer interně. Klasický algoritmus kruhového bufferu vyhrazuje jeden bajt pro sledování, takže alokovaný buffer je o jeden bajt větší než size a instance pojme plných size bajtů dat. Například RingIO(16) alokuje 17bajtový buffer a pojme 16 bajtů dat.

• RingIO(buffer) používá dodaný buffer přímo namísto alokace nového. Protože je jeden bajt vyhrazen pro sledování, instance pojme len(buffer) - 1 bajtů dat. Například RingIO(bytearray(16)) pojme 15 bajtů dat.

Instance RingIO je bezpečná vůči IRQ/vláknům, když se používá k předávání dat v jediném směru (například zápis z IRQ a čtení z funkce mimo IRQ, nebo naopak). To neplatí, pokud se do jediné instance zapisuje z kontextu IRQ i mimo IRQ, což by často způsobilo poškození dat.

any() → int

Vrátí celé číslo udávající počet znaků, které lze přečíst.

read(nbytes: int | None = None) → bytes

Přečte dostupné znaky. Toto je neblokující funkce. Pokud je zadáno nbytes, přečte nanejvýš tolik bajtů, jinak přečte co nejvíce dat.

Návratová hodnota: objekt bytes obsahující přečtené bajty. Bude to objekt bytes nulové délky, pokud nejsou dostupná žádná data.

readline(nbytes: int | None = None) → bytes

Přečte řádek zakončený znakem nového řádku nebo návratu, pokud takový v bufferu existuje, jinak vrátí dostupné bajty v bufferu. Pokud je zadáno nbytes, přečte nanejvýš tolik bajtů.

Návratová hodnota: objekt bytes obsahující přečtený řádek.

readinto(buf: bytearray | memoryview, nbytes: int | None = None) → int

Přečte dostupné bajty do poskytnutého buf. Pokud je zadáno nbytes, přečte nanejvýš tolik bajtů. Jinak přečte nanejvýš len(buf) bajtů.

Návratová hodnota: celočíselný počet bajtů přečtených do buf.

write(buf: bytes | bytearray | memoryview) → int

Neblokující zápis bajtů z buf do kruhového bufferu, omezený dostupným místem v kruhovém bufferu.

Návratová hodnota: celočíselný počet zapsaných bajtů.

close() → None

Operace bez efektu poskytovaná jako součást standardního stream rozhraní. Na data v kruhovém bufferu nemá žádný vliv.