`stubber.publish.stubpackage`¶

Create a stub-only package for a specific version of micropython

Module Contents¶

Classes¶

`VersionedPackage`	Represents a versioned package.
`Builder`	Builder class for creating and updating MicroPython stub packages.
`PoetryBuilder`	Build a package using Poetry
`StubPackage`	Create a stub-only package for a specific version , port and board of micropython

Attributes¶

`Status`
`StubSources`
`STUBS_COPY_FILTER`
`STDLIB_UMODULES`

stubber.publish.stubpackage.Status¶

stubber.publish.stubpackage.StubSources¶

stubber.publish.stubpackage.STUBS_COPY_FILTER¶

stubber.publish.stubpackage.STDLIB_UMODULES = ['ucollections']¶

class stubber.publish.stubpackage.VersionedPackage(package_name: str, *, mpy_version: str)¶

Bases: object

Represents a versioned package.

Parameters:

package_name (str) –
mpy_version (str) –

package_name¶

The name of the package.

Type:: str

mpy_version¶

The MicroPython version.

Type:: str

__init__(self, package_name: str, mpy_version: str): Initializes a new instance of the VersionedPackage class.

is_preview(self)¶: Checks if the package is a preview version.

pkg_version(self) → str¶

Returns the version of the package.

Return type:: str

pkg_version(self, version: str) -> None: Sets the version of the package.

get_prerelease_package_version(self, production: bool = False) -> str: Gets the next prerelease version for the package.

get_next_package_version(self, prod: bool = False, rc=False) -> str: Gets the next version for the package.

next_pkg_version(self, production: bool) -> str: Gets the next version for the package.

bump(self, *, rc: int = 0) -> str: Bumps the postrelease version of the package.

property pkg_version: str¶

return the version of the package

Return type:: str

__str__() → str¶

Return str(self).

Return type:: str

__repr__() → str¶

Return repr(self).

Return type:: str

__eq__(o: object) → bool¶

Return self==value.

Parameters:: o (object) –
Return type:: bool

__hash__() → int¶

Return hash(self).

Return type:: int

next_package_version(production: bool) → str¶

Get the next version for the package

Parameters:: production (bool) –
Return type:: str

is_preview()¶

_get_next_preview_package_version(production: bool = False) → str¶

Get the next prerelease version for the package. this is used for preview versions of micropython (-preview, formerly known as ‘latest’)

Parameters:: production (bool) –
Return type:: str

_get_next_package_version(prod: bool = False, rc=False) → str¶

Get the next version for the package.

Parameters:: prod (bool) –
Return type:: str

bump(*, rc: int = 0) → str¶

bump the postrelease version of the package, and write the change to disk if rc >= 1, the version is bumped to the specified release candidate

Parameters:: rc (int) –
Return type:: str

class stubber.publish.stubpackage.Builder(package_name: str, *, mpy_version: str = '0.0.1', port: str, board: str = GENERIC_U, description: str = 'MicroPython stubs', stubs: StubSources | None = None)¶

Bases: VersionedPackage

Builder class for creating and updating MicroPython stub packages.

Parameters:

package_name (str) – The name of the package.
mpy_version (str, optional) – The version of MicroPython. Defaults to “0.0.1”.
port (str) – The port for the package.
board (str, optional) – The board for the package. Defaults to GENERIC_U.
description (str, optional) – The description of the package. Defaults to “MicroPython stubs”.
stubs (Optional[StubSources], optional) – The stub sources for the package. Defaults to None.

package_name¶

The name of the package.

Type:: str

mpy_version¶

The version of MicroPython.

Type:: str

port¶

The port for the package.

Type:: str

board¶

The board for the package.

Type:: str

description¶

The description of the package.

Type:: str

stub_sources¶

The stub sources for the package.

Type:: Optional[StubSources]

hash¶

The hash of all the files in the package.

Type:: None

stub_hash¶

The hash of the stub files.

Type:: None

Properties:: package_path (Path): The package path based on the package name and version, relative to the publish folder. toml_path (Path): The path to the pyproject.toml file. pyproject (Union[Dict[str, Any], None]): The parsed pyproject.toml or None.

create_update_pyproject_toml()¶

Create or update/overwrite a pyproject.toml file.

Return type:: None

check()¶

Check if the package is valid.

Return type:: bool

clean()¶

Remove the stub files from the package folder.

Return type:: None

copy_stubs()¶

Copy files from all listed stub folders to the package folder.

Return type:: None

update_package_files()¶

Update the stub-only package for a specific version of MicroPython.

Return type:: None

write_package_json()¶

Write the package.json file to disk.

Return type:: None

to_dict()¶

Return the package as a dict to store in the jsondb.

Return type:: dict

from_dict(json_data: Dict): Load the package from a dict (from the jsondb).

calculate_hash(include_md: bool = True): Create a SHA1 hash of all files in the package.

update_hashes()¶

Update the package hashes.

Return type:: None

is_changed(include_md: bool = True): Check if the package has changed.

property package_path: pathlib.Path¶

package path based on the package name and version and relative to the publish folder

Return type:: pathlib.Path

property toml_path: pathlib.Path¶

the path to the pyproject.toml file

Return type:: pathlib.Path

property pyproject: Dict[str, Any] | None¶

parsed pyproject.toml or None

Return type:: Union[Dict[str, Any], None]

BUF_SIZE¶

hash¶: Hash of all the files in the package

stub_hash¶: Hash of all .pyi files

abstract create_update_pyproject_toml() → None¶

create or update/overwrite a pyproject.toml file by combining a template file with the given parameters.

Return type:: None

check() → bool¶

Check if the package is valid, to be implemented by the subclass

Return type:: bool

clean() → None¶

Remove the stub files from the package folder

This is used before update the stub package, to avoid lingering stub files, and after the package has been built, to avoid needing to store files multiple times.

.gitignore cannot be used as this will prevent poetry from processing the files.

Return type:: None

copy_stubs() → None¶

Copy files from all listed stub folders to the package folder the order of the stub folders is relevant as “last copy wins”

1 - Copy all firmware stubs/merged to the package folder

2 - copy the remaining stubs to the package folder

3 - remove *.py files from the package folder

Return type:: None

update_umodules()¶: Replace the STDLIB umodules with a simple import statement in order to allow the typecheckers to resove the stdlib modules in the usual stdlib location.

copy_folder(stub_type: stubber.publish.enums.StubSource, src_path: pathlib.Path)¶

Parameters:

stub_type (stubber.publish.enums.StubSource) –
src_path (pathlib.Path) –

update_package_files() → None¶

Update the stub-only package for a specific version of micropython

cleans the package folder
copies the stubs from the list of stubs.
creates/updates the readme and the license file

Return type:: None

write_package_json() → None¶

write the package.json file to disk

Return type:: None

to_dict() → dict¶

return the package as a dict to store in the jsondb

need to simplify some of the Objects to allow serialization to json - the paths to posix paths - the version (semver) to a string - toml file to list of lines

Return type:: dict

from_dict(json_data: Dict) → None¶

load the package from a dict (from the jsondb)

Parameters:: json_data (Dict) –
Return type:: None

calculate_hash(include_md: bool = True) → str¶

Create a SHA1 hash of all files in the package, excluding the pyproject.toml file itself. the hash is based on the content of the .py/.pyi and .md files in the package. if include_md is False , the .md files are not hased, allowing the files in the packeges to be compared simply As a single hash is created across all files, the files are sorted prior to hashing to ensure that the hash is stable.

Note: A changed hash will not indicate which of the files in the package have been changed.

Parameters:: include_md (bool) –
Return type:: str

add_file_hash(file, file_hash)¶

Adds the hash of a file to the given file hash object. If an error occurs, the file is retried up to 3 times with a 0.2 second delay

Parameters:

file (str) – The path to the file.
file_hash (hashlib._Hash) – The file hash object to update.

Returns:

None

update_hashes(ret=False) → None¶

Update the package hashes. Resets is_changed() to False

Return type:: None

is_changed(include_md: bool = True) → bool¶

Check if the package has changed, based on the current and the stored hash. The default checks the hash of all files, including the .md files.

Parameters:: include_md (bool) –
Return type:: bool

create_license() → None¶

Create a license file for the package

copied from the template license file

Return type:: None

create_readme() → None¶

Create a readme file for the package

based on the template readme file
with a list of all included stub folders added to it (not the individual stub-files)

Return type:: None

class stubber.publish.stubpackage.PoetryBuilder(package_name: str, *, port: str, mpy_version: str = '0.0.1', board: str = GENERIC_U, description: str = 'MicroPython stubs', stubs: StubSources | None = None, json_data: Dict[str, Any] | None = None)¶

Bases: Builder

Build a package using Poetry

Parameters:

package_name (str) –
port (str) –
mpy_version (str) –
board (str) –
description (str) –
stubs (Optional[StubSources]) –
json_data (Optional[Dict[str, Any]]) –

property pkg_version: str¶

return the version of the package

Return type:: str

poetry_build() → bool¶

build the package by running poetry build

Return type:: bool

poetry_publish(production: bool = False) → bool¶

Parameters:: production (bool) –
Return type:: bool

run_poetry(parameters: List[str]) → bool¶

Run a poetry commandline in the package folder. Note: this may write some output to the console (‘All set!’)

Parameters:: parameters (List[str]) –
Return type:: bool

check() → bool¶

check if the package is valid by running poetry check Note: this will write some output to the console (‘All set!’)

Return type:: bool

create_update_pyproject_toml() → None¶

create or update/overwrite a pyproject.toml file by combining a template file with the given parameters. and updating it with the pyi files included

Return type:: None

update_pyproject_stubs() → int¶

Add the stub files to the pyproject.toml file

Return type:: int

class stubber.publish.stubpackage.StubPackage(package_name: str, port: str, *, board: str = GENERIC_U, version: str = '0.0.1', description: str = 'MicroPython stubs', stubs: StubSources | None = None, json_data: Dict[str, Any] | None = None)¶

Bases: PoetryBuilder

Create a stub-only package for a specific version , port and board of micropython

properties:

toml_path - the path to the pyproject.toml file
package_path - the path to the folder where the package info will be stored (‘./publish’).
pkg_version - the version of the package as used on PyPi (semver). Is stored directly in the pyproject.toml file
pyproject - the contents of the pyproject.toml file

Parameters:

package_name (str) –
port (str) –
board (str) –
version (str) –
description (str) –
stubs (Optional[StubSources]) –
json_data (Optional[Dict[str, Any]]) –

- from_json - load the package from json

- to_json - return the package as json

- create_update_pyproject_toml - create or update the `pyproject.toml` file

- create_readme - create the readme file

- create_license - create the license file

- copy_stubs - copy the stubs to the package folder

- update_included_stubs - update the included stubs in the `pyproject.toml` file

- create_hash - create a hash of the package files

- update_package_files - combines clean, copy, and create reeadme & updates

update_sources() → StubSources¶

Update the stub sources to: - FIRMWARE: prefer -merged stubs over bare firmware stubs - FROZEN: fallback to use the GENERIC folder for the frozen sources if no board specific folder exists

Return type:: StubSources

update_distribution(production: bool) → bool¶

Update the package .pyi files, if all the sources are available

Parameters:: production (bool) –
Return type:: bool

build_distribution(production: bool, force=False) → bool¶

Build a package look up the previous package version in the dabase

update package files

build the wheels and sdist

Parameters:

production (bool) – PyPI or Test-PyPi -
force – BUILD even if no changes

Returns:

True if the package was built

Return type:

bool

publish_distribution_ifchanged(db: pysondb.PysonDB, *, production: bool, build=False, force=False, dry_run=False, clean: bool = False) → bool¶

Publish a package to PyPi look up the previous package version in the dabase, and only publish if there are changes to the package - change determied by hash across all files

Build

update package files
build the wheels and sdist

Publish

publish to PyPi
update database with new hash

Parameters:

db (pysondb.PysonDB) –
production (bool) –
clean (bool) –

Return type:

bool

publish_distribution(dry_run, production, db)¶

Publishes the package to PyPi or Test-PyPi.

Parameters:

dry_run (bool) – If True, performs a dry run without actually publishing.
production (bool) – If True, publishes to PyPi. If False, publishes to Test-PyPi.
db – The database object to save the package state.

Returns:

True if the publish was successful, False otherwise.

Return type:

bool

are_package_sources_available() → bool¶

Check if (all) the packages sources exist.

Return type:: bool

stubber.publish.stubpackage¶

Module Contents¶

Classes¶

Attributes¶

`stubber.publish.stubpackage`¶