# Glossary

This glossary defines common terms used throughout the MicroPython Stubber documentation.

## General Terms

(board)=
**Board**
: A physical microcontroller development board (e.g., ESP32, Raspberry Pi Pico, PyBoard) that runs MicroPython firmware.

(cpython)=
**CPython**
: The reference implementation of Python, typically running on desktop/server systems. Different from MicroPython in available modules and memory constraints.

(firmware)=
**Firmware**
: The MicroPython software that runs on a microcontroller board. Different firmware versions support different modules and features.

(firmware-id)=
**Firmware ID**
: A unique identifier for a specific firmware build, typically including family, version, and port (e.g., `micropython-v1.22.2-esp32`).

(ide)=
**IDE**
: Integrated Development Environment - a software application providing comprehensive facilities for software development (e.g., VS Code, PyCharm).

(intellisense)=
**IntelliSense**
: Microsoft's code completion, parameter info, quick info, and member lists feature in VS Code and other editors.

(mcu)=
**MCU**
: Microcontroller Unit - the chip that runs MicroPython firmware as part of a product or on a development board.

(port)=
**Port**
: A version of MicroPython adapted for a specific microcontroller family or platform (e.g., esp32, rp2, stm32).

(repl)=
**REPL**
: Read-Eval-Print Loop - the interactive MicroPython prompt where you can type commands and see immediate results.

## Stub-Related Terms

(core-stubs)=
**Core Stubs**
: Stub files for Python standard library modules that provide compatibility between MicroPython and CPython.

(doc-stubs)=
**Doc Stubs**
: Stub files generated by parsing the official MicroPython documentation (RST files). These include detailed parameter information and docstrings.

(frozen-modules)=
**Frozen Modules**
: Python modules that are compiled into the MicroPython firmware at build time to save memory. These modules are stored in flash memory rather than as separate .py files.

(frozen-stubs)=
**Frozen Stubs**
: Stub files generated from the source code of frozen modules found in MicroPython firmware repositories.

(mcu-stubs)=
**Firmware Stubs**
: Stub files generated directly on a MicroPython device by introspecting available modules and their attributes (previously called MCU stubs; the `mcu-stubs` CLI alias remains available). These have limited parameter information due to memory constraints. The stored stub source name remains "MCU stubs" for database and manifest compatibility.

(minified-stubs)=
**Minified Stubs**
: Compressed versions of stub generation scripts optimized for deployment on memory-constrained MicroPython devices.

(module-manifest)=
**Module Manifest**
: A JSON file (`modules.json`) that contains metadata about generated stubs, including board information, firmware version, and list of successfully stubbed modules.

(stub-files)=
**Stub Files**
: Python files with `.pyi` extensions that contain type hints and interface definitions without implementation code. Used by IDEs and type checkers for code completion and error detection.

(type-hints)=
**Type Hints**
: Annotations in Python code that specify the expected types of variables, function parameters, and return values, following PEP 484 standards.

## Tools and Commands

(createstubspy)=
**createstubs.py**
: The main script that runs on MicroPython devices to generate stub files by introspecting available modules.

(mpremote)=
**mpremote**
: A command-line tool for interacting with MicroPython devices over serial connections.

(pylance)=
**Pylance**
: Microsoft's Python language server that provides IntelliSense, type checking, and other language features in VS Code.

(stubgen)=
**stubgen**
: A tool (part of mypy) that automatically generates stub files from Python source code.

(stubber)=
**stubber**
: The main command-line interface for MicroPython Stubber, providing various subcommands for stub generation and management.

## File Extensions and Formats

(py-files)=
**.py Files**
: Regular Python source code files containing implementation.

(pyi-files)=
**.pyi Files**
: Python stub files containing only type information and interface definitions, no implementation.

(modulesjson)=
**modules.json**
: A manifest file containing metadata about generated stubs and the device they were created on.

## MicroPython-Specific Terms

(sysimplementation)=
**sys.implementation**
: A Python module attribute that provides information about the Python implementation (name, version, etc.).

(sysuname)=
**sys.uname()**
: A MicroPython function that returns system information including platform, architecture, and version details.

(upip)=
**upip**
: MicroPython's package installer (predecessor to mip).

(mip)=
**mip**
: MicroPython's modern package installer for installing packages from PyPI or other sources.

(flash-memory)=
**Flash Memory**
: Non-volatile storage on microcontroller boards where firmware and frozen modules are stored.

(sd-card)=
**SD Card**
: External storage that can be used with some MicroPython boards for additional file storage.

## Development Workflow Terms

(clone)=
**Clone**
: To create a local copy of a Git repository, typically the MicroPython source code repositories.

(repository)=
**Repository (Repo)**
: A Git repository containing source code, typically hosted on GitHub.

(switch)=
**Switch**
: To change between different versions, branches, or commits in a Git repository.

(merge)=
**Merge**
: To combine different types of stub files (doc, frozen, MCU) into a unified set.

(build)=
**Build**
: To create distributable packages from stub files for publication to PyPI.

(publish)=
**Publish**
: To upload stub packages to PyPI or other package repositories.

(version)=
**Version**
: A specific release or commit of MicroPython firmware (e.g., v1.22.2, stable, preview).

## Configuration Terms

(pyprojecttoml)=
**pyproject.toml**
: A configuration file used by modern Python tools including Poetry for project metadata and dependencies.

(pylint)=
**Pylint**
: A Python static code analysis tool that looks for programming errors, helps enforce coding standards, and suggests refactoring.

(type-checking)=
**Type Checking**
: The process of verifying that code uses types consistently and correctly, typically done by tools like mypy or Pylance.

(workspace)=
**Workspace**
: A VS Code concept representing a folder or set of folders that contain your project files and configuration.

## Error and Debugging Terms

(memory-allocation-bug)=
**Memory Allocation Bug**
: A specific issue in MicroPython 1.13.0 that prevents stub generation from working properly.

(notimplementederror)=
**NotImplementedError**
: A Python exception raised when attempting to use functionality that isn't available or implemented.

(problematic-modules)=
**Problematic Modules**
: MicroPython modules that cannot be safely introspected for stub generation due to side effects or system requirements.

(excluded-modules)=
**Excluded Modules**
: Modules that are intentionally skipped during stub generation because they provide no useful type information.

---

*This glossary is maintained as part of the MicroPython Stubber documentation. Terms are added and updated as the project evolves.*