stubber.publish.candidates
==========================

.. py:module:: stubber.publish.candidates

.. autoapi-nested-parse::

   In order to generate stups for all ports and boars and versions of micropython we need to know
   what versions are available. This module provides functions to :
       - get a list of all ports for a given version of micropython  ( list micropython ports)
       - get a list of all ports and board for a given version of micropython (list micropython ports boards)

           - get a list of versions for micropython ( version candidates)
       - get the frozen stubs for a given version of micropython ( frozen candidates)
       - get a list of all the docstubs (docstub candidates)
       - get a list of the firmware stubs (firmware candidates, formerly called MCU stubs)



Functions
---------

.. autoapisummary::

   stubber.publish.candidates.subfolder_names
   stubber.publish.candidates.version_candidates
   stubber.publish.candidates.list_frozen_ports
   stubber.publish.candidates.list_micropython_ports
   stubber.publish.candidates.list_micropython_port_boards
   stubber.publish.candidates.frozen_candidates
   stubber.publish.candidates.is_auto
   stubber.publish.candidates.board_candidates
   stubber.publish.candidates.filter_list


Module Contents
---------------

.. py:function:: subfolder_names(path: pathlib.Path)

   returns a list of names of the sub folders of the given path


.. py:function:: version_candidates(suffix: str, prefix: str = '.*', *, path: pathlib.Path = CONFIG.stub_path, oldest: str = OLDEST_VERSION) -> Generator[str, None, None]

   get a list of versions for the given family and suffix


.. py:function:: list_frozen_ports(family: str = 'micropython', version: str = V_PREVIEW, path: pathlib.Path = CONFIG.stub_path)

   get list of ports with frozen stubs for a given family and version


.. py:function:: list_micropython_ports(family: str = 'micropython', mpy_path: pathlib.Path = CONFIG.mpy_path)

   get list of micropython ports for a given family and version


.. py:function:: list_micropython_port_boards(port: str, family: str = 'micropython', mpy_path: pathlib.Path = CONFIG.mpy_path)

   get list of micropython boards for a given family version and board


.. py:function:: frozen_candidates(family: str = 'micropython', versions: Union[str, List[str]] = V_PREVIEW, ports: Union[str, List[str]] = 'all', boards: Union[str, List[str]] = 'all', *, path: pathlib.Path = CONFIG.stub_path) -> Generator[Dict[str, Any], None, None]

   generate a list of possible firmware stubs for the given family (, version port and board)
   - family = micropython
       board and port are ignored, they are looked up from the available frozen stubs
   - versions = 'latest' , 'auto' or a list of versions
   - port = 'auto' or a specific port
   - board = 'auto' or a specific board, 'generic' must be specified in lowercare


.. py:function:: is_auto(thing: Union[None, str, List[str]])

   Is this version/port/board specified as 'auto' ?


.. py:function:: board_candidates(family: str = 'micropython', versions: Union[str, List[str]] = V_PREVIEW, *, mpy_path: pathlib.Path = CONFIG.mpy_path)

   generate a list of possible board stub candidates for the given family and version.
   list is based on the micropython repo:  /ports/<list of ports>/boards/<list of boards>


.. py:function:: filter_list(worklist: List[Dict[str, str]], ports: Optional[Union[List[str], str]] = None, boards: Optional[Union[List[str], str]] = None)

   filter a list of candidates down to the ones we want, based on the ports and boards specified (case insensitive)
   for board also match using a 'GENERIC_' prefix, so board 's3' will match candidate 'GENERIC_S3'