From f539ee3e149c26bdf5774af1f81e7c0562488c68 Mon Sep 17 00:00:00 2001 From: Robert Walton Date: Fri, 25 Mar 2022 14:27:56 +0000 Subject: [PATCH 1/8] Remove pdoc3 documentation We don't want to use this tool or the documentation generated by it, due to its use of controversial imagery in the auto generated HTML. --- README.md | 1 - azure-pipelines/analyse-and-test.yml | 25 -- ci_scripts/prep-release | 6 +- docs/api/build/build.html | 184 --------- docs/api/build/config.html | 178 -------- docs/api/build/exceptions.html | 218 ---------- docs/api/build/flash.html | 173 -------- docs/api/build/index.html | 107 ----- docs/api/cli/build.html | 199 --------- docs/api/cli/configure.html | 145 ------- docs/api/cli/index.html | 103 ----- docs/api/cli/list_connected_devices.html | 172 -------- docs/api/cli/main.html | 245 ----------- docs/api/cli/project_management.html | 163 -------- docs/api/cli/sterm.html | 117 ------ docs/api/devices/device.html | 447 -------------------- docs/api/devices/devices.html | 310 -------------- docs/api/devices/exceptions.html | 189 --------- docs/api/devices/index.html | 104 ----- docs/api/index.html | 101 ----- docs/api/lib/exceptions.html | 109 ----- docs/api/lib/index.html | 91 ---- docs/api/lib/json_helpers.html | 108 ----- docs/api/lib/logging.html | 267 ------------ docs/api/lib/python_helpers.html | 135 ------ docs/api/project/exceptions.html | 219 ---------- docs/api/project/index.html | 99 ----- docs/api/project/mbed_program.html | 503 ----------------------- docs/api/project/project.html | 297 ------------- docs/api/sterm/index.html | 76 ---- docs/api/sterm/terminal.html | 419 ------------------- docs/api/targets/board.html | 364 ---------------- docs/api/targets/boards.html | 362 ---------------- docs/api/targets/env.html | 300 -------------- docs/api/targets/exceptions.html | 223 ---------- docs/api/targets/get_board.html | 342 --------------- docs/api/targets/get_target.html | 191 --------- docs/api/targets/index.html | 140 ------- news/202203251430.misc | 1 + pyproject.toml | 2 - setup.py | 1 - src/mbed_tools/targets/env.py | 5 - tox.ini | 5 - 43 files changed, 3 insertions(+), 7443 deletions(-) delete mode 100644 docs/api/build/build.html delete mode 100644 docs/api/build/config.html delete mode 100644 docs/api/build/exceptions.html delete mode 100644 docs/api/build/flash.html delete mode 100644 docs/api/build/index.html delete mode 100644 docs/api/cli/build.html delete mode 100644 docs/api/cli/configure.html delete mode 100644 docs/api/cli/index.html delete mode 100644 docs/api/cli/list_connected_devices.html delete mode 100644 docs/api/cli/main.html delete mode 100644 docs/api/cli/project_management.html delete mode 100644 docs/api/cli/sterm.html delete mode 100644 docs/api/devices/device.html delete mode 100644 docs/api/devices/devices.html delete mode 100644 docs/api/devices/exceptions.html delete mode 100644 docs/api/devices/index.html delete mode 100644 docs/api/index.html delete mode 100644 docs/api/lib/exceptions.html delete mode 100644 docs/api/lib/index.html delete mode 100644 docs/api/lib/json_helpers.html delete mode 100644 docs/api/lib/logging.html delete mode 100644 docs/api/lib/python_helpers.html delete mode 100644 docs/api/project/exceptions.html delete mode 100644 docs/api/project/index.html delete mode 100644 docs/api/project/mbed_program.html delete mode 100644 docs/api/project/project.html delete mode 100644 docs/api/sterm/index.html delete mode 100644 docs/api/sterm/terminal.html delete mode 100644 docs/api/targets/board.html delete mode 100644 docs/api/targets/boards.html delete mode 100644 docs/api/targets/env.html delete mode 100644 docs/api/targets/exceptions.html delete mode 100644 docs/api/targets/get_board.html delete mode 100644 docs/api/targets/get_target.html delete mode 100644 docs/api/targets/index.html create mode 100644 news/202203251430.misc diff --git a/README.md b/README.md index 1e1820a3..ba162103 100644 --- a/README.md +++ b/README.md @@ -77,7 +77,6 @@ production release here: The follow described the major aspects of the project structure: - `azure-pipelines/` - CI configuration files for Azure Pipelines. -- `docs/api` - Interface definition and usage documentation. - `src/mbed_tools/` - Python source files. - `news/` - Collection of news files for unreleased changes. - `tests/` - Unit and integration tests. diff --git a/azure-pipelines/analyse-and-test.yml b/azure-pipelines/analyse-and-test.yml index c58e288a..15614fe7 100644 --- a/azure-pipelines/analyse-and-test.yml +++ b/azure-pipelines/analyse-and-test.yml @@ -3,7 +3,6 @@ # This pipeline performs multiple actions to ensure the quality of the package: # - Performs static analysis and runs test on multiple Python versions and host platforms. # - Uploads test coverage to Code Climate -# - Generates reference documentation # Trigger on a PR to master, beta or releases branches. pr: @@ -112,27 +111,3 @@ stages: displayName: run tox -e $(tox.env) - template: steps/publish-code-coverage-results.yml - - - stage: DocBuild - displayName: 'Build Documentation' - dependsOn: [] - jobs: - - job: Docs - displayName: 'Build Documentation' - pool: - vmImage: 'ubuntu-latest' - - steps: - - task: UsePythonVersion@0 - displayName: 'Use Python 3.7' - inputs: - versionSpec: '3.7' - - - script: | - python -m pip install --upgrade tox - tox -e generatedocs -- $(Build.Repository.LocalPath)/docs/api - displayName: run tox -e generatedocs -- $(Build.Repository.LocalPath)/docs/api - - - publish: $(Build.Repository.LocalPath)/docs/api - artifact: Documentation - displayName: 'Publish documentation' diff --git a/ci_scripts/prep-release b/ci_scripts/prep-release index a97b0da5..d67f1ab5 100755 --- a/ci_scripts/prep-release +++ b/ci_scripts/prep-release @@ -10,10 +10,8 @@ python ci_scripts/sync_board_database.py -vvv git add src/mbed_tools/targets/_internal/data/board_database_snapshot.json git add news/ -printf "Generating API docs and adding license headers\n" -generate-docs --output_dir docs/api +printf "Adding license headers\n" pre-commit run licenseheaders --all-files > /dev/null 2>&1 || true -git add docs/api if ! NEW_VERSION=$(python ci_scripts/bump_version.py -vvv -n news/); then printf "No news files detected. Exiting.\n" @@ -25,7 +23,7 @@ git update-index -q --ignore-submodules --refresh if ! git diff-index --cached --quiet HEAD --ignore-submodules -- then - printf "Found staged changes to commit after docs and target database update: $(git diff-index --cached --name-status --ignore-submodules HEAD)\n" + printf "Found staged changes to commit after target database update: $(git diff-index --cached --name-status --ignore-submodules HEAD)\n" # Towncrier will fail if it detects a news file that has not been committed to # the repository. So we need to ensure the news file generated by # sync_board_database.py was committed before running towncrier. diff --git a/docs/api/build/build.html b/docs/api/build/build.html deleted file mode 100644 index 0c755c58..00000000 --- a/docs/api/build/build.html +++ /dev/null @@ -1,184 +0,0 @@ - - - - - - -mbed_tools.build.build API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.build.build

-
-
-

Configure and build a CMake project.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Configure and build a CMake project."""
-import logging
-import pathlib
-import subprocess
-
-from typing import Optional
-
-from mbed_tools.build.exceptions import MbedBuildError
-
-
-logger = logging.getLogger(__name__)
-
-
-def build_project(build_dir: pathlib.Path, target: Optional[str] = None) -> None:
-    """Build a project using CMake to invoke Ninja.
-
-    Args:
-        build_dir: Path to the CMake build tree.
-        target: The CMake target to build (e.g 'install')
-    """
-    _check_ninja_found()
-    target_flag = ["--target", target] if target is not None else []
-    _cmake_wrapper("--build", str(build_dir), *target_flag)
-
-
-def generate_build_system(source_dir: pathlib.Path, build_dir: pathlib.Path, profile: str) -> None:
-    """Configure a project using CMake.
-
-    Args:
-        source_dir: Path to the CMake source tree.
-        build_dir: Path to the CMake build tree.
-        profile: The Mbed build profile (develop, debug or release).
-    """
-    _check_ninja_found()
-    _cmake_wrapper("-S", str(source_dir), "-B", str(build_dir), "-GNinja", f"-DCMAKE_BUILD_TYPE={profile}")
-
-
-def _cmake_wrapper(*cmake_args: str) -> None:
-    try:
-        logger.debug("Running CMake with args: %s", cmake_args)
-        subprocess.run(["cmake", *cmake_args], check=True)
-    except FileNotFoundError:
-        raise MbedBuildError("Could not find CMake. Please ensure CMake is installed and added to PATH.")
-    except subprocess.CalledProcessError:
-        raise MbedBuildError("CMake invocation failed!")
-
-
-def _check_ninja_found() -> None:
-    try:
-        subprocess.run(["ninja", "--version"], check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
-    except FileNotFoundError:
-        raise MbedBuildError(
-            "Could not find the 'Ninja' build program. Please ensure 'Ninja' is installed and added to PATH."
-        )
-
-
-
-
-
-
-
-

Functions

-
-
-def build_project(build_dir: pathlib.Path, target: Optional[str] = None) ‑> None -
-
-

Build a project using CMake to invoke Ninja.

-

Args

-
-
build_dir
-
Path to the CMake build tree.
-
target
-
The CMake target to build (e.g 'install')
-
-
- -Expand source code - -
def build_project(build_dir: pathlib.Path, target: Optional[str] = None) -> None:
-    """Build a project using CMake to invoke Ninja.
-
-    Args:
-        build_dir: Path to the CMake build tree.
-        target: The CMake target to build (e.g 'install')
-    """
-    _check_ninja_found()
-    target_flag = ["--target", target] if target is not None else []
-    _cmake_wrapper("--build", str(build_dir), *target_flag)
-
-
-
-def generate_build_system(source_dir: pathlib.Path, build_dir: pathlib.Path, profile: str) ‑> None -
-
-

Configure a project using CMake.

-

Args

-
-
source_dir
-
Path to the CMake source tree.
-
build_dir
-
Path to the CMake build tree.
-
profile
-
The Mbed build profile (develop, debug or release).
-
-
- -Expand source code - -
def generate_build_system(source_dir: pathlib.Path, build_dir: pathlib.Path, profile: str) -> None:
-    """Configure a project using CMake.
-
-    Args:
-        source_dir: Path to the CMake source tree.
-        build_dir: Path to the CMake build tree.
-        profile: The Mbed build profile (develop, debug or release).
-    """
-    _check_ninja_found()
-    _cmake_wrapper("-S", str(source_dir), "-B", str(build_dir), "-GNinja", f"-DCMAKE_BUILD_TYPE={profile}")
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/build/config.html b/docs/api/build/config.html deleted file mode 100644 index 3de336c5..00000000 --- a/docs/api/build/config.html +++ /dev/null @@ -1,178 +0,0 @@ - - - - - - -mbed_tools.build.config API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.build.config

-
-
-

Parses the Mbed configuration system and generates a CMake config script.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Parses the Mbed configuration system and generates a CMake config script."""
-import pathlib
-
-from typing import Any, Tuple
-
-from mbed_tools.lib.json_helpers import decode_json_file
-from mbed_tools.project import MbedProgram
-from mbed_tools.targets import get_target_by_name
-from mbed_tools.build._internal.cmake_file import render_mbed_config_cmake_template
-from mbed_tools.build._internal.config.assemble_build_config import Config, assemble_config
-from mbed_tools.build._internal.write_files import write_file
-from mbed_tools.build.exceptions import MbedBuildError
-
-CMAKE_CONFIG_FILE = "mbed_config.cmake"
-MBEDIGNORE_FILE = ".mbedignore"
-
-
-def generate_config(target_name: str, toolchain: str, program: MbedProgram) -> Tuple[Config, pathlib.Path]:
-    """Generate an Mbed config file after parsing the Mbed config system.
-
-    Args:
-        target_name: Name of the target to configure for.
-        toolchain: Name of the toolchain to use.
-        program: The MbedProgram to configure.
-
-    Returns:
-        Config object (UserDict).
-        Path to the generated config file.
-    """
-    targets_data = _load_raw_targets_data(program)
-    target_build_attributes = get_target_by_name(target_name, targets_data)
-    config = assemble_config(
-        target_build_attributes, [program.root, program.mbed_os.root], program.files.app_config_file
-    )
-    cmake_file_contents = render_mbed_config_cmake_template(
-        target_name=target_name, config=config, toolchain_name=toolchain,
-    )
-    cmake_config_file_path = program.files.cmake_build_dir / CMAKE_CONFIG_FILE
-    write_file(cmake_config_file_path, cmake_file_contents)
-    mbedignore_path = program.files.cmake_build_dir / MBEDIGNORE_FILE
-    write_file(mbedignore_path, "*")
-    return config, cmake_config_file_path
-
-
-def _load_raw_targets_data(program: MbedProgram) -> Any:
-    targets_data = decode_json_file(program.mbed_os.targets_json_file)
-    if program.files.custom_targets_json.exists():
-        custom_targets_data = decode_json_file(program.files.custom_targets_json)
-        for custom_target in custom_targets_data:
-            if custom_target in targets_data:
-                raise MbedBuildError(
-                    f"Error found in {program.files.custom_targets_json}.\n"
-                    f"A target with the name '{custom_target}' already exists in targets.json. "
-                    "Please give your custom target a unique name so it can be identified."
-                )
-
-        targets_data.update(custom_targets_data)
-
-    return targets_data
-
-
-
-
-
-
-
-

Functions

-
-
-def generate_config(target_name: str, toolchain: str, program: MbedProgram) ‑> Tuple[mbed_tools.build._internal.config.config.Config, pathlib.Path] -
-
-

Generate an Mbed config file after parsing the Mbed config system.

-

Args

-
-
target_name
-
Name of the target to configure for.
-
toolchain
-
Name of the toolchain to use.
-
program
-
The MbedProgram to configure.
-
-

Returns

-

Config object (UserDict). -Path to the generated config file.

-
- -Expand source code - -
def generate_config(target_name: str, toolchain: str, program: MbedProgram) -> Tuple[Config, pathlib.Path]:
-    """Generate an Mbed config file after parsing the Mbed config system.
-
-    Args:
-        target_name: Name of the target to configure for.
-        toolchain: Name of the toolchain to use.
-        program: The MbedProgram to configure.
-
-    Returns:
-        Config object (UserDict).
-        Path to the generated config file.
-    """
-    targets_data = _load_raw_targets_data(program)
-    target_build_attributes = get_target_by_name(target_name, targets_data)
-    config = assemble_config(
-        target_build_attributes, [program.root, program.mbed_os.root], program.files.app_config_file
-    )
-    cmake_file_contents = render_mbed_config_cmake_template(
-        target_name=target_name, config=config, toolchain_name=toolchain,
-    )
-    cmake_config_file_path = program.files.cmake_build_dir / CMAKE_CONFIG_FILE
-    write_file(cmake_config_file_path, cmake_file_contents)
-    mbedignore_path = program.files.cmake_build_dir / MBEDIGNORE_FILE
-    write_file(mbedignore_path, "*")
-    return config, cmake_config_file_path
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/build/exceptions.html b/docs/api/build/exceptions.html deleted file mode 100644 index 5f5e6b30..00000000 --- a/docs/api/build/exceptions.html +++ /dev/null @@ -1,218 +0,0 @@ - - - - - - -mbed_tools.build.exceptions API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.build.exceptions

-
-
-

Public exceptions raised by the package.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Public exceptions raised by the package."""
-from mbed_tools.lib.exceptions import ToolsError
-
-
-class MbedBuildError(ToolsError):
-    """Base public exception for the mbed-build package."""
-
-
-class InvalidExportOutputDirectory(MbedBuildError):
-    """It is not possible to export to the provided output directory."""
-
-
-class BinaryFileNotFoundError(MbedBuildError):
-    """The binary file (.bin/.hex) cannot be found in cmake_build directory."""
-
-
-class DeviceNotFoundError(MbedBuildError):
-    """The requested device is not connected to your system."""
-
-
-class InvalidConfigOverride(MbedBuildError):
-    """A given config setting was invalid."""
-
-
-
-
-
-
-
-
-
-

Classes

-
-
-class BinaryFileNotFoundError -(*args, **kwargs) -
-
-

The binary file (.bin/.hex) cannot be found in cmake_build directory.

-
- -Expand source code - -
class BinaryFileNotFoundError(MbedBuildError):
-    """The binary file (.bin/.hex) cannot be found in cmake_build directory."""
-
-

Ancestors

- -
-
-class DeviceNotFoundError -(*args, **kwargs) -
-
-

The requested device is not connected to your system.

-
- -Expand source code - -
class DeviceNotFoundError(MbedBuildError):
-    """The requested device is not connected to your system."""
-
-

Ancestors

- -
-
-class InvalidConfigOverride -(*args, **kwargs) -
-
-

A given config setting was invalid.

-
- -Expand source code - -
class InvalidConfigOverride(MbedBuildError):
-    """A given config setting was invalid."""
-
-

Ancestors

- -
-
-class InvalidExportOutputDirectory -(*args, **kwargs) -
-
-

It is not possible to export to the provided output directory.

-
- -Expand source code - -
class InvalidExportOutputDirectory(MbedBuildError):
-    """It is not possible to export to the provided output directory."""
-
-

Ancestors

- -
-
-class MbedBuildError -(*args, **kwargs) -
-
-

Base public exception for the mbed-build package.

-
- -Expand source code - -
class MbedBuildError(ToolsError):
-    """Base public exception for the mbed-build package."""
-
-

Ancestors

-
    -
  • ToolsError
    • -
  • builtins.Exception
    • -
  • builtins.BaseException
    • -
-

Subclasses

- -
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/build/flash.html b/docs/api/build/flash.html deleted file mode 100644 index 8bccc6e4..00000000 --- a/docs/api/build/flash.html +++ /dev/null @@ -1,173 +0,0 @@ - - - - - - -mbed_tools.build.flash API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.build.flash

-
-
-

Flash binary onto the connected device.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Flash binary onto the connected device."""
-
-import shutil
-import os
-import pathlib
-import platform
-
-from mbed_tools.build.exceptions import BinaryFileNotFoundError
-
-
-def _flash_dev(disk: pathlib.Path, image_path: pathlib.Path) -> None:
-    """Flash device using copy method.
-
-    Args:
-        disk: Device mount point.
-        image_path: Image file to be copied to device.
-    """
-    shutil.copy(image_path, disk, follow_symlinks=False)
-    if not platform.system() == "Windows":
-        os.sync()
-
-
-def _build_binary_file_path(program_path: pathlib.Path, build_dir: pathlib.Path, hex_file: bool) -> pathlib.Path:
-    """Build binary file name.
-
-    Args:
-       program_path: Path to the Mbed project.
-       build_dir: Path to the CMake build folder.
-       hex_file: Use hex file.
-
-    Returns:
-        Path to binary file.
-
-    Raises:
-        BinaryFileNotFoundError: binary file not found in the path specified
-    """
-    fw_fbase = build_dir / program_path.name
-    fw_file = fw_fbase.with_suffix(".hex" if hex_file else ".bin")
-    if not fw_file.exists():
-        raise BinaryFileNotFoundError(f"Build program file (firmware) not found {fw_file}")
-    return fw_file
-
-
-def flash_binary(
-    mount_point: pathlib.Path, program_path: pathlib.Path, build_dir: pathlib.Path, mbed_target: str, hex_file: bool
-) -> pathlib.Path:
-    """Flash binary onto a device.
-
-    Look through the connected devices and flash the binary if the connected and built target matches.
-
-    Args:
-       mount_point: Mount point of the target device.
-       program_path: Path to the Mbed project.
-       build_dir: Path to the CMake build folder.
-       mbed_target: The name of the Mbed target to build for.
-       hex_file: Use hex file.
-    """
-    fw_file = _build_binary_file_path(program_path, build_dir, hex_file)
-    _flash_dev(mount_point, fw_file)
-    return fw_file
-
-
-
-
-
-
-
-

Functions

-
-
-def flash_binary(mount_point: pathlib.Path, program_path: pathlib.Path, build_dir: pathlib.Path, mbed_target: str, hex_file: bool) ‑> pathlib.Path -
-
-

Flash binary onto a device.

-

Look through the connected devices and flash the binary if the connected and built target matches.

-

Args

-
-
mount_point
-
Mount point of the target device.
-
program_path
-
Path to the Mbed project.
-
build_dir
-
Path to the CMake build folder.
-
mbed_target
-
The name of the Mbed target to build for.
-
hex_file
-
Use hex file.
-
-
- -Expand source code - -
def flash_binary(
-    mount_point: pathlib.Path, program_path: pathlib.Path, build_dir: pathlib.Path, mbed_target: str, hex_file: bool
-) -> pathlib.Path:
-    """Flash binary onto a device.
-
-    Look through the connected devices and flash the binary if the connected and built target matches.
-
-    Args:
-       mount_point: Mount point of the target device.
-       program_path: Path to the Mbed project.
-       build_dir: Path to the CMake build folder.
-       mbed_target: The name of the Mbed target to build for.
-       hex_file: Use hex file.
-    """
-    fw_file = _build_binary_file_path(program_path, build_dir, hex_file)
-    _flash_dev(mount_point, fw_file)
-    return fw_file
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/build/index.html b/docs/api/build/index.html deleted file mode 100644 index 05c66de0..00000000 --- a/docs/api/build/index.html +++ /dev/null @@ -1,107 +0,0 @@ - - - - - - -mbed_tools.build API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.build

-
-
-

Provides the core build system for Mbed OS, which relies on CMake and Ninja as underlying technologies.

-

The functionality covered in this package includes the following:

-
    -
  • Execution of Mbed Pre-Build stages to determine appropriate configuration for Mbed OS and the build process.
    • -
  • Invocation of the build process for the command line tools and online build service.
    • -
  • Export of build instructions to third party command line tools and IDEs.
    • -
-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Provides the core build system for Mbed OS, which relies on CMake and Ninja as underlying technologies.
-
-The functionality covered in this package includes the following:
-
-- Execution of Mbed Pre-Build stages to determine appropriate configuration for Mbed OS and the build process.
-- Invocation of the build process for the command line tools and online build service.
-- Export of build instructions to third party command line tools and IDEs.
-"""
-from mbed_tools.build.build import build_project, generate_build_system
-from mbed_tools.build.config import generate_config
-from mbed_tools.build.flash import flash_binary
-
-
-
-

Sub-modules

-
-
mbed_tools.build.build
-
-

Configure and build a CMake project.

-
-
mbed_tools.build.config
-
-

Parses the Mbed configuration system and generates a CMake config script.

-
-
mbed_tools.build.exceptions
-
-

Public exceptions raised by the package.

-
-
mbed_tools.build.flash
-
-

Flash binary onto the connected device.

-
-
-
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/cli/build.html b/docs/api/cli/build.html deleted file mode 100644 index c1f681e4..00000000 --- a/docs/api/cli/build.html +++ /dev/null @@ -1,199 +0,0 @@ - - - - - - -mbed_tools.cli.build API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.cli.build

-
-
-

Command to build/compile an Mbed project using CMake.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Command to build/compile an Mbed project using CMake."""
-import os
-import pathlib
-import shutil
-
-from typing import Optional, Tuple
-
-import click
-
-from mbed_tools.build import build_project, generate_build_system, generate_config, flash_binary
-from mbed_tools.devices import find_connected_device, find_all_connected_devices
-from mbed_tools.project import MbedProgram
-from mbed_tools.sterm import terminal
-
-
-@click.command(name="compile", help="Build an Mbed project.")
-@click.option(
-    "-t",
-    "--toolchain",
-    type=click.Choice(["ARM", "GCC_ARM"], case_sensitive=False),
-    required=True,
-    help="The toolchain you are using to build your app.",
-)
-@click.option("-m", "--mbed-target", required=True, help="A build target for an Mbed-enabled device, e.g. K64F.")
-@click.option("-b", "--profile", default="develop", help="The build type (release, develop or debug).")
-@click.option("-c", "--clean", is_flag=True, default=False, help="Perform a clean build.")
-@click.option(
-    "-p",
-    "--program-path",
-    default=os.getcwd(),
-    help="Path to local Mbed program. By default it is the current working directory.",
-)
-@click.option(
-    "--mbed-os-path", type=click.Path(), default=None, help="Path to local Mbed OS directory.",
-)
-@click.option(
-    "--custom-targets-json", type=click.Path(), default=None, help="Path to custom_targets.json.",
-)
-@click.option(
-    "--app-config", type=click.Path(), default=None, help="Path to application configuration file.",
-)
-@click.option(
-    "-f", "--flash", is_flag=True, default=False, help="Flash the binary onto a device",
-)
-@click.option(
-    "-s", "--sterm", is_flag=True, default=False, help="Launch a serial terminal to the device.",
-)
-@click.option(
-    "--baudrate",
-    default=9600,
-    show_default=True,
-    help="Change the serial baud rate (ignored unless --sterm is also given).",
-)
-def build(
-    program_path: str,
-    profile: str,
-    toolchain: str,
-    mbed_target: str,
-    clean: bool,
-    flash: bool,
-    sterm: bool,
-    baudrate: int,
-    mbed_os_path: str,
-    custom_targets_json: str,
-    app_config: str,
-) -> None:
-    """Configure and build an Mbed project using CMake and Ninja.
-
-    If the CMake configuration step has already been run previously (i.e a CMake build tree exists), then just try to
-    build the project immediately using Ninja.
-
-    Args:
-       program_path: Path to the Mbed project.
-       mbed_os_path: The path to the local Mbed OS directory.
-       profile: The Mbed build profile (debug, develop or release).
-       custom_targets_json: Path to custom_targets.json.
-       toolchain: The toolchain to use for the build.
-       mbed_target: The name of the Mbed target to build for.
-       app_config: the path to the application configuration file
-       clean: Perform a clean build.
-       flash: Flash the binary onto a device.
-       sterm: Open a serial terminal to the connected target.
-       baudrate: Change the serial baud rate (ignored unless --sterm is also given).
-    """
-    mbed_target, target_id = _get_target_id(mbed_target)
-
-    cmake_build_subdir = pathlib.Path(mbed_target.upper(), profile.lower(), toolchain.upper())
-    if mbed_os_path is None:
-        program = MbedProgram.from_existing(pathlib.Path(program_path), cmake_build_subdir)
-    else:
-        program = MbedProgram.from_existing(pathlib.Path(program_path), cmake_build_subdir, pathlib.Path(mbed_os_path))
-    build_tree = program.files.cmake_build_dir
-    if clean and build_tree.exists():
-        shutil.rmtree(build_tree)
-
-    click.echo("Configuring project and generating build system...")
-    if custom_targets_json is not None:
-        program.files.custom_targets_json = pathlib.Path(custom_targets_json)
-    if app_config is not None:
-        program.files.app_config_file = pathlib.Path(app_config)
-    config, _ = generate_config(mbed_target.upper(), toolchain, program)
-    generate_build_system(program.root, build_tree, profile)
-
-    click.echo("Building Mbed project...")
-    build_project(build_tree)
-
-    if flash or sterm:
-        if target_id is not None or sterm:
-            devices = [find_connected_device(mbed_target, target_id)]
-        else:
-            devices = find_all_connected_devices(mbed_target)
-
-    if flash:
-        for dev in devices:
-            hex_file = "OUTPUT_EXT" in config and config["OUTPUT_EXT"] == "hex"
-            flashed_path = flash_binary(dev.mount_points[0].resolve(), program.root, build_tree, mbed_target, hex_file)
-        click.echo(f"Copied {str(flashed_path.resolve())} to {len(devices)} device(s).")
-
-    if sterm:
-        dev = devices[0]
-        if dev.serial_port is None:
-            raise click.ClickException(
-                f"The connected device {dev.mbed_board.board_name} does not have an associated serial port."
-                " Reconnect the device and try again."
-            )
-
-        terminal.run(dev.serial_port, baudrate)
-
-
-def _get_target_id(target: str) -> Tuple[str, Optional[int]]:
-    if "[" in target:
-        target_name, target_id = target.replace("]", "").split("[", maxsplit=1)
-        if target_id.isdigit() and int(target_id) >= 0:
-            return (target_name, int(target_id))
-        raise click.ClickException("When using the format mbed-target[ID], ID must be a positive integer or 0.")
-    return (target, None)
-
-
-
-
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/cli/configure.html b/docs/api/cli/configure.html deleted file mode 100644 index 8b8f4a79..00000000 --- a/docs/api/cli/configure.html +++ /dev/null @@ -1,145 +0,0 @@ - - - - - - -mbed_tools.cli.configure API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.cli.configure

-
-
-

Command to generate the application CMake configuration script used by the build/compile system.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Command to generate the application CMake configuration script used by the build/compile system."""
-import pathlib
-
-import click
-
-from mbed_tools.project import MbedProgram
-from mbed_tools.build import generate_config
-
-
-@click.command(
-    help="Generate an Mbed OS config CMake file and write it to a .mbedbuild folder in the program directory."
-)
-@click.option(
-    "--custom-targets-json", type=click.Path(), default=None, help="Path to custom_targets.json.",
-)
-@click.option(
-    "-t",
-    "--toolchain",
-    type=click.Choice(["ARM", "GCC_ARM"], case_sensitive=False),
-    required=True,
-    help="The toolchain you are using to build your app.",
-)
-@click.option("-m", "--mbed-target", required=True, help="A build target for an Mbed-enabled device, eg. K64F")
-@click.option("-b", "--profile", default="develop", help="The build type (release, develop or debug).")
-@click.option("-o", "--output-dir", type=click.Path(), default=None, help="Path to output directory.")
-@click.option(
-    "-p",
-    "--program-path",
-    type=click.Path(),
-    default=".",
-    help="Path to local Mbed program. By default is the current working directory.",
-)
-@click.option(
-    "--mbed-os-path", type=click.Path(), default=None, help="Path to local Mbed OS directory.",
-)
-@click.option(
-    "--app-config", type=click.Path(), default=None, help="Path to application configuration file.",
-)
-def configure(
-    toolchain: str,
-    mbed_target: str,
-    profile: str,
-    program_path: str,
-    mbed_os_path: str,
-    output_dir: str,
-    custom_targets_json: str,
-    app_config: str
-) -> None:
-    """Exports a mbed_config.cmake file to build directory in the program root.
-
-    The parameters set in the CMake file will be dependent on the combination of
-    toolchain and Mbed target provided and these can then control which parts of
-    Mbed OS are included in the build.
-
-    This command will create the .mbedbuild directory at the program root if it doesn't
-    exist.
-
-    Args:
-        custom_targets_json: the path to custom_targets.json
-        toolchain: the toolchain you are using (eg. GCC_ARM, ARM)
-        mbed_target: the target you are building for (eg. K64F)
-        profile: The Mbed build profile (debug, develop or release).
-        program_path: the path to the local Mbed program
-        mbed_os_path: the path to the local Mbed OS directory
-        output_dir: the path to the output directory
-        app_config: the path to the application configuration file
-    """
-    cmake_build_subdir = pathlib.Path(mbed_target.upper(), profile.lower(), toolchain.upper())
-    if mbed_os_path is None:
-        program = MbedProgram.from_existing(pathlib.Path(program_path), cmake_build_subdir)
-    else:
-        program = MbedProgram.from_existing(pathlib.Path(program_path), cmake_build_subdir, pathlib.Path(mbed_os_path))
-    if custom_targets_json is not None:
-        program.files.custom_targets_json = pathlib.Path(custom_targets_json)
-    if output_dir is not None:
-        program.files.cmake_build_dir = pathlib.Path(output_dir)
-    if app_config is not None:
-        program.files.app_config_file = pathlib.Path(app_config)
-
-    mbed_target = mbed_target.upper()
-    _, output_path = generate_config(mbed_target, toolchain, program)
-    click.echo(f"mbed_config.cmake has been generated and written to '{str(output_path.resolve())}'")
-
-
-
-
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/cli/index.html b/docs/api/cli/index.html deleted file mode 100644 index 3bc1ac48..00000000 --- a/docs/api/cli/index.html +++ /dev/null @@ -1,103 +0,0 @@ - - - - - - -mbed_tools.cli API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.cli

-
-
-

mbed_tools command line interface.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""mbed_tools command line interface."""
-
-from mbed_tools.cli.main import cli, LOGGER
-
-
-
-

Sub-modules

-
-
mbed_tools.cli.build
-
-

Command to build/compile an Mbed project using CMake.

-
-
mbed_tools.cli.configure
-
-

Command to generate the application CMake configuration script used by the build/compile system.

-
-
mbed_tools.cli.list_connected_devices
-
-

Command to list all Mbed enabled devices connected to the host computer.

-
-
mbed_tools.cli.main
-
-

Main cli entry point.

-
-
mbed_tools.cli.project_management
-
-

Project management commands: new, import_, deploy and libs.

-
-
mbed_tools.cli.sterm
-
-

Command to launch a serial terminal to a connected Mbed device.

-
-
-
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/cli/list_connected_devices.html b/docs/api/cli/list_connected_devices.html deleted file mode 100644 index fbcdf348..00000000 --- a/docs/api/cli/list_connected_devices.html +++ /dev/null @@ -1,172 +0,0 @@ - - - - - - -mbed_tools.cli.list_connected_devices API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.cli.list_connected_devices

-
-
-

Command to list all Mbed enabled devices connected to the host computer.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Command to list all Mbed enabled devices connected to the host computer."""
-import click
-import json
-from operator import attrgetter
-from typing import Iterable, List, Optional, Tuple
-from tabulate import tabulate
-
-from mbed_tools.devices import get_connected_devices, Device
-from mbed_tools.targets import Board
-
-
-@click.command()
-@click.option(
-    "--format", type=click.Choice(["table", "json"]), default="table", show_default=True, help="Set output format."
-)
-@click.option(
-    "--show-all",
-    "-a",
-    is_flag=True,
-    default=False,
-    help="Show all connected devices, even those which are not Mbed Boards.",
-)
-def list_connected_devices(format: str, show_all: bool) -> None:
-    """Prints connected devices."""
-    connected_devices = get_connected_devices()
-
-    if show_all:
-        devices = _sort_devices(connected_devices.identified_devices + connected_devices.unidentified_devices)
-    else:
-        devices = _sort_devices(connected_devices.identified_devices)
-
-    output_builders = {
-        "table": _build_tabular_output,
-        "json": _build_json_output,
-    }
-    if devices:
-        output = output_builders[format](devices)
-        click.echo(output)
-    else:
-        click.echo("No connected Mbed devices found.")
-
-
-def _sort_devices(devices: Iterable[Device]) -> Iterable[Device]:
-    """Sort devices by board name and then serial number (in case there are multiple boards with the same name)."""
-    return sorted(devices, key=attrgetter("mbed_board.board_name", "serial_number"))
-
-
-def _get_devices_ids(devices: Iterable[Device]) -> List[Tuple[Optional[int], Device]]:
-    """Create tuple of ID and Device for each Device. ID is None when only one Device exists with a given board name."""
-    devices_ids: List[Tuple[Optional[int], Device]] = []
-    n = 0
-    for device in devices:
-        board_name = device.mbed_board.board_name
-        if len([dev for dev in devices if dev.mbed_board.board_name == board_name]) > 1:
-            devices_ids.append((n, device))
-            n += 1
-        else:
-            devices_ids.append((None, device))
-            n = 0
-    return devices_ids
-
-
-def _build_tabular_output(devices: Iterable[Device]) -> str:
-    headers = ["Board name", "Serial number", "Serial port", "Mount point(s)", "Build target(s)", "Interface Version"]
-    devices_data = []
-    for id, device in _get_devices_ids(devices):
-        devices_data.append(
-            [
-                device.mbed_board.board_name or "<unknown>",
-                device.serial_number,
-                device.serial_port or "<unknown>",
-                "\n".join(str(mount_point) for mount_point in device.mount_points),
-                "\n".join(_get_build_targets(device.mbed_board, id)),
-                device.interface_version,
-            ]
-        )
-    return tabulate(devices_data, headers=headers, numalign="left")
-
-
-def _build_json_output(devices: Iterable[Device]) -> str:
-    devices_data = []
-    for id, device in _get_devices_ids(devices):
-        board = device.mbed_board
-        devices_data.append(
-            {
-                "serial_number": device.serial_number,
-                "serial_port": device.serial_port,
-                "mount_points": [str(m) for m in device.mount_points],
-                "interface_version": device.interface_version,
-                "mbed_board": {
-                    "product_code": board.product_code,
-                    "board_type": board.board_type,
-                    "board_name": board.board_name,
-                    "mbed_os_support": board.mbed_os_support,
-                    "mbed_enabled": board.mbed_enabled,
-                    "build_targets": _get_build_targets(board, id),
-                },
-            }
-        )
-    return json.dumps(devices_data, indent=4)
-
-
-def _get_build_targets(board: Board, identifier: Optional[int]) -> List[str]:
-    if identifier is not None:
-        return [f"{board.board_type}_{variant}[{identifier}]" for variant in board.build_variant] + [
-            f"{board.board_type}[{identifier}]"
-        ]
-    else:
-        return [f"{board.board_type}_{variant}" for variant in board.build_variant] + [board.board_type]
-
-
-
-
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/cli/main.html b/docs/api/cli/main.html deleted file mode 100644 index 884121e3..00000000 --- a/docs/api/cli/main.html +++ /dev/null @@ -1,245 +0,0 @@ - - - - - - -mbed_tools.cli.main API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.cli.main

-
-
-

Main cli entry point.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Main cli entry point."""
-import logging
-import sys
-
-from pkg_resources import get_distribution
-from typing import Union, Any
-
-import click
-
-from mbed_tools.lib.logging import set_log_level, MbedToolsHandler
-
-from mbed_tools.cli.configure import configure
-from mbed_tools.cli.list_connected_devices import list_connected_devices
-from mbed_tools.cli.project_management import new, import_, deploy
-from mbed_tools.cli.build import build
-from mbed_tools.cli.sterm import sterm
-
-CONTEXT_SETTINGS = dict(help_option_names=["-h", "--help"])
-LOGGER = logging.getLogger(__name__)
-
-
-class GroupWithExceptionHandling(click.Group):
-    """A click.Group which handles ToolsErrors and logging."""
-
-    def invoke(self, context: click.Context) -> None:
-        """Invoke the command group.
-
-        Args:
-            context: The current click context.
-        """
-        # Use the context manager to ensure tools exceptions (expected behaviour) are shown as messages to the user,
-        # but all other exceptions (unexpected behaviour) are shown as errors.
-        with MbedToolsHandler(LOGGER, context.params["traceback"]) as handler:
-            super().invoke(context)
-
-        sys.exit(handler.exit_code)
-
-
-def print_version(context: click.Context, param: Union[click.Option, click.Parameter], value: bool) -> Any:
-    """Print the version of mbed-tools."""
-    if not value or context.resilient_parsing:
-        return
-
-    version_string = get_distribution("mbed-tools").version
-    click.echo(version_string)
-    context.exit()
-
-
-@click.group(cls=GroupWithExceptionHandling, context_settings=CONTEXT_SETTINGS)
-@click.option(
-    "--version",
-    is_flag=True,
-    callback=print_version,
-    expose_value=False,
-    is_eager=True,
-    help="Display versions of all Mbed Tools packages.",
-)
-@click.option(
-    "-v",
-    "--verbose",
-    default=0,
-    count=True,
-    help="Set the verbosity level, enter multiple times to increase verbosity.",
-)
-@click.option("-t", "--traceback", is_flag=True, show_default=True, help="Show a traceback when an error is raised.")
-def cli(verbose: int, traceback: bool) -> None:
-    """Command line tool for interacting with Mbed OS."""
-    set_log_level(verbose)
-
-
-cli.add_command(configure, "configure")
-cli.add_command(list_connected_devices, "detect")
-cli.add_command(new, "new")
-cli.add_command(deploy, "deploy")
-cli.add_command(import_, "import")
-cli.add_command(build, "compile")
-cli.add_command(sterm, "sterm")
-
-
-
-
-
-
-
-

Functions

-
-
-def print_version(context: click.core.Context, param: Union[click.core.Option, click.core.Parameter], value: bool) ‑> Any -
-
-

Print the version of mbed-tools.

-
- -Expand source code - -
def print_version(context: click.Context, param: Union[click.Option, click.Parameter], value: bool) -> Any:
-    """Print the version of mbed-tools."""
-    if not value or context.resilient_parsing:
-        return
-
-    version_string = get_distribution("mbed-tools").version
-    click.echo(version_string)
-    context.exit()
-
-
-
-
-
-

Classes

-
-
-class GroupWithExceptionHandling -(name=None, commands=None, **attrs) -
-
-

A click.Group which handles ToolsErrors and logging.

-
- -Expand source code - -
class GroupWithExceptionHandling(click.Group):
-    """A click.Group which handles ToolsErrors and logging."""
-
-    def invoke(self, context: click.Context) -> None:
-        """Invoke the command group.
-
-        Args:
-            context: The current click context.
-        """
-        # Use the context manager to ensure tools exceptions (expected behaviour) are shown as messages to the user,
-        # but all other exceptions (unexpected behaviour) are shown as errors.
-        with MbedToolsHandler(LOGGER, context.params["traceback"]) as handler:
-            super().invoke(context)
-
-        sys.exit(handler.exit_code)
-
-

Ancestors

-
    -
  • click.core.Group
    • -
  • click.core.MultiCommand
    • -
  • click.core.Command
    • -
  • click.core.BaseCommand
    • -
-

Methods

-
-
-def invoke(self, context: click.core.Context) ‑> None -
-
-

Invoke the command group.

-

Args

-
-
context
-
The current click context.
-
-
- -Expand source code - -
def invoke(self, context: click.Context) -> None:
-    """Invoke the command group.
-
-    Args:
-        context: The current click context.
-    """
-    # Use the context manager to ensure tools exceptions (expected behaviour) are shown as messages to the user,
-    # but all other exceptions (unexpected behaviour) are shown as errors.
-    with MbedToolsHandler(LOGGER, context.params["traceback"]) as handler:
-        super().invoke(context)
-
-    sys.exit(handler.exit_code)
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/cli/project_management.html b/docs/api/cli/project_management.html deleted file mode 100644 index 80fcb86a..00000000 --- a/docs/api/cli/project_management.html +++ /dev/null @@ -1,163 +0,0 @@ - - - - - - -mbed_tools.cli.project_management API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.cli.project_management

-
-
-

Project management commands: new, import_, deploy and libs.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Project management commands: new, import_, deploy and libs."""
-import os
-import pathlib
-
-from typing import Any, List
-
-import click
-import tabulate
-
-from mbed_tools.project import initialise_project, import_project, get_known_libs, deploy_project
-from mbed_tools.project._internal import git_utils
-
-
-@click.command()
-@click.option("--create-only", "-c", is_flag=True, show_default=True, help="Create a program without fetching mbed-os.")
-@click.argument("path", type=click.Path(resolve_path=True))
-def new(path: str, create_only: bool) -> None:
-    """Creates a new Mbed project at the specified path. Downloads mbed-os and adds it to the project.
-
-    PATH: Path to the destination directory for the project. Will be created if it does not exist.
-    """
-    click.echo(f"Creating a new Mbed program at path '{path}'.")
-    if not create_only:
-        click.echo("Downloading mbed-os and adding it to the project.")
-
-    initialise_project(pathlib.Path(path), create_only)
-
-
-@click.command()
-@click.argument("url")
-@click.argument("path", type=click.Path(), default="")
-@click.option(
-    "--skip-resolve-libs",
-    "-s",
-    is_flag=True,
-    show_default=True,
-    help="Skip resolving program library dependencies after cloning.",
-)
-def import_(url: str, path: Any, skip_resolve_libs: bool) -> None:
-    """Clone an Mbed project and library dependencies.
-
-    URL: The git url of the remote project to clone.
-
-    PATH: Destination path for the clone. If not given the destination path is set to the project name in the cwd.
-    """
-    click.echo(f"Cloning Mbed program '{url}'")
-    if not skip_resolve_libs:
-        click.echo("Resolving program library dependencies.")
-
-    if path:
-        click.echo(f"Destination path is '{path}'")
-        path = pathlib.Path(path)
-
-    dst_path = import_project(url, path, not skip_resolve_libs)
-    if not skip_resolve_libs:
-        libs = get_known_libs(dst_path)
-        _print_dependency_table(libs)
-
-
-@click.command()
-@click.argument("path", type=click.Path(), default=os.getcwd())
-@click.option(
-    "--force",
-    "-f",
-    is_flag=True,
-    show_default=True,
-    help="Forces checkout of all library repositories at specified commit in the .lib file, overwrites local changes.",
-)
-def deploy(path: str, force: bool) -> None:
-    """Checks out Mbed program library dependencies at the revision specified in the ".lib" files.
-
-    Ensures all dependencies are resolved and the versions are synchronised to the version specified in the library
-    reference.
-
-    PATH: Path to the Mbed project [default: CWD]
-    """
-    click.echo("Checking out all libraries to revisions specified in .lib files. Resolving any unresolved libraries.")
-    root_path = pathlib.Path(path)
-    deploy_project(root_path, force)
-    libs = get_known_libs(root_path)
-    _print_dependency_table(libs)
-
-
-def _print_dependency_table(libs: List) -> None:
-    click.echo("The following library dependencies were fetched: \n")
-    table = []
-    for lib in libs:
-        table.append(
-            [
-                lib.reference_file.stem,
-                lib.get_git_reference().repo_url,
-                lib.source_code_path,
-                git_utils.get_default_branch(git_utils.get_repo(lib.source_code_path))
-                if not lib.get_git_reference().ref
-                else lib.get_git_reference().ref,
-            ]
-        )
-
-    headers = ("Library Name", "Repository URL", "Path", "Git Reference")
-    click.echo(tabulate.tabulate(table, headers=headers))
-
-
-
-
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/cli/sterm.html b/docs/api/cli/sterm.html deleted file mode 100644 index 1b5b2ce7..00000000 --- a/docs/api/cli/sterm.html +++ /dev/null @@ -1,117 +0,0 @@ - - - - - - -mbed_tools.cli.sterm API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.cli.sterm

-
-
-

Command to launch a serial terminal to a connected Mbed device.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Command to launch a serial terminal to a connected Mbed device."""
-from typing import Any, Optional
-
-import click
-
-from mbed_tools.cli.build import _get_target_id
-from mbed_tools.devices import find_connected_device, get_connected_devices
-from mbed_tools.devices.exceptions import MbedDevicesError
-from mbed_tools.sterm import terminal
-
-
-@click.command(
-    help="Open a serial terminal to a connected Mbed Enabled device, or connect to a user-specified COM port."
-)
-@click.option(
-    "-p",
-    "--port",
-    type=str,
-    help="Communication port. Default: auto-detect. Specifying this will also ignore the -m/--mbed-target option.",
-)
-@click.option("-b", "--baudrate", type=int, default=9600, show_default=True, help="Communication baudrate.")
-@click.option(
-    "-e",
-    "--echo",
-    default="on",
-    show_default=True,
-    type=click.Choice(["on", "off"], case_sensitive=False),
-    help="Switch local echo on/off.",
-)
-@click.option("-m", "--mbed-target", type=str, help="Mbed target to detect. Example: K64F, NUCLEO_F401RE, NRF51822...")
-def sterm(port: str, baudrate: int, echo: str, mbed_target: str) -> None:
-    """Launches a serial terminal to a connected device."""
-    if port is None:
-        port = _find_target_serial_port_or_default(mbed_target)
-
-    terminal.run(port, baudrate, echo=True if echo == "on" else False)
-
-
-def _get_connected_mbed_devices() -> Any:
-    connected_devices = get_connected_devices()
-    if not connected_devices.identified_devices:
-        raise MbedDevicesError("No Mbed enabled devices found.")
-
-    return connected_devices.identified_devices
-
-
-def _find_target_serial_port_or_default(target: Optional[str]) -> Any:
-    if target is None:
-        # just return the first valid device found
-        device, *_ = _get_connected_mbed_devices()
-    else:
-        target_name, target_id = _get_target_id(target)
-        device = find_connected_device(target_name.upper(), target_id)
-    return device.serial_port
-
-
-
-
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/devices/device.html b/docs/api/devices/device.html deleted file mode 100644 index 2d66c3c2..00000000 --- a/docs/api/devices/device.html +++ /dev/null @@ -1,447 +0,0 @@ - - - - - - -mbed_tools.devices.device API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.devices.device

-
-
-

Data model definition for Device and ConnectedDevices.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Data model definition for Device and ConnectedDevices."""
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Tuple, Optional, List
-from mbed_tools.targets import Board
-from mbed_tools.devices._internal.detect_candidate_devices import CandidateDevice
-from mbed_tools.devices._internal.resolve_board import resolve_board, NoBoardForCandidate, ResolveBoardError
-from mbed_tools.devices._internal.file_parser import read_device_files
-from mbed_tools.devices.exceptions import DeviceLookupFailed
-
-
-@dataclass(frozen=True, order=True)
-class Device:
-    """Definition of an Mbed Enabled Device.
-
-    An Mbed Device is always a USB mass storage device, which sometimes also presents a USB serial port.
-    A valid Mbed Device must have a Board associated with it.
-
-    Attributes:
-        mbed_board: The Board associated with this device.
-        serial_number: The serial number presented by the device to the USB subsystem.
-        serial_port: The serial port presented by this device, could be None.
-        mount_points: The filesystem mount points associated with this device.
-    """
-
-    mbed_board: Board
-    serial_number: str
-    serial_port: Optional[str]
-    mount_points: Tuple[Path, ...]
-    mbed_enabled: bool = False
-    interface_version: Optional[str] = None
-
-    @classmethod
-    def from_candidate(cls, candidate: CandidateDevice) -> "Device":
-        """Contruct a Device from a CandidateDevice.
-
-        We try to resolve a board using data files that may be stored on the CandidateDevice.
-        If this fails we set the board to `None` which means we couldn't verify this Device
-        as being an Mbed enabled device.
-
-        Args:
-            candidate: The CandidateDevice we're using to create the Device.
-        """
-        device_file_info = read_device_files(candidate.mount_points)
-        try:
-            mbed_board = resolve_board(
-                device_file_info.product_code, device_file_info.online_id, candidate.serial_number
-            )
-            mbed_enabled = True
-        except NoBoardForCandidate:
-            # Create an empty Board to ensure the device is fully populated and rendering is simple
-            mbed_board = Board.from_offline_board_entry({})
-            mbed_enabled = False
-        except ResolveBoardError:
-            raise DeviceLookupFailed(
-                f"Failed to resolve the board for candidate device {candidate!r}. There was a problem looking up the "
-                "board data in the database."
-            )
-
-        return Device(
-            serial_port=candidate.serial_port,
-            serial_number=candidate.serial_number,
-            mount_points=candidate.mount_points,
-            mbed_board=mbed_board,
-            mbed_enabled=mbed_enabled,
-            interface_version=device_file_info.interface_details.get("Version"),
-        )
-
-
-@dataclass(order=True)
-class ConnectedDevices:
-    """Definition of connected devices which may be Mbed Boards.
-
-    If a connected device is identified as an Mbed Board by using the HTM file on the USB mass storage device (or
-    sometimes by using the serial number), it will be included in the `identified_devices` list.
-
-    However, if the device appears as if it could be an Mbed Board but it has not been possible to find a matching
-    entry in the database then it will be included in the `unidentified_devices` list.
-
-    Attributes:
-        identified_devices: A list of devices that have been identified as MbedTargets.
-        unidentified_devices: A list of devices that could potentially be MbedTargets.
-    """
-
-    identified_devices: List[Device] = field(default_factory=list)
-    unidentified_devices: List[Device] = field(default_factory=list)
-
-    def add_device(self, device: Device) -> None:
-        """Add a device to the connected devices.
-
-        Args:
-            device: a Device object containing the device information.
-        """
-        if not device.mbed_enabled:
-            # Keep a list of devices that could not be identified but are Mbed Boards
-            self.unidentified_devices.append(device)
-        else:
-            # Keep a list of devices that have been identified as Mbed Boards
-            self.identified_devices.append(device)
-
-
-
-
-
-
-
-
-
-

Classes

-
-
-class ConnectedDevices -(identified_devices: List[Device] = <factory>, unidentified_devices: List[Device] = <factory>) -
-
-

Definition of connected devices which may be Mbed Boards.

-

If a connected device is identified as an Mbed Board by using the HTM file on the USB mass storage device (or -sometimes by using the serial number), it will be included in the identified_devices list.

-

However, if the device appears as if it could be an Mbed Board but it has not been possible to find a matching -entry in the database then it will be included in the unidentified_devices list.

-

Attributes

-
-
identified_devices
-
A list of devices that have been identified as MbedTargets.
-
unidentified_devices
-
A list of devices that could potentially be MbedTargets.
-
-
- -Expand source code - -
class ConnectedDevices:
-    """Definition of connected devices which may be Mbed Boards.
-
-    If a connected device is identified as an Mbed Board by using the HTM file on the USB mass storage device (or
-    sometimes by using the serial number), it will be included in the `identified_devices` list.
-
-    However, if the device appears as if it could be an Mbed Board but it has not been possible to find a matching
-    entry in the database then it will be included in the `unidentified_devices` list.
-
-    Attributes:
-        identified_devices: A list of devices that have been identified as MbedTargets.
-        unidentified_devices: A list of devices that could potentially be MbedTargets.
-    """
-
-    identified_devices: List[Device] = field(default_factory=list)
-    unidentified_devices: List[Device] = field(default_factory=list)
-
-    def add_device(self, device: Device) -> None:
-        """Add a device to the connected devices.
-
-        Args:
-            device: a Device object containing the device information.
-        """
-        if not device.mbed_enabled:
-            # Keep a list of devices that could not be identified but are Mbed Boards
-            self.unidentified_devices.append(device)
-        else:
-            # Keep a list of devices that have been identified as Mbed Boards
-            self.identified_devices.append(device)
-
-

Class variables

-
-
var identified_devices : List[Device]
-
-
-
-
var unidentified_devices : List[Device]
-
-
-
-
-

Methods

-
-
-def add_device(self, device: Device) ‑> None -
-
-

Add a device to the connected devices.

-

Args

-
-
device
-
a Device object containing the device information.
-
-
- -Expand source code - -
def add_device(self, device: Device) -> None:
-    """Add a device to the connected devices.
-
-    Args:
-        device: a Device object containing the device information.
-    """
-    if not device.mbed_enabled:
-        # Keep a list of devices that could not be identified but are Mbed Boards
-        self.unidentified_devices.append(device)
-    else:
-        # Keep a list of devices that have been identified as Mbed Boards
-        self.identified_devices.append(device)
-
-
-
-
-
-class Device -(mbed_board: Board, serial_number: str, serial_port: Optional[str], mount_points: Tuple[pathlib.Path, ...], mbed_enabled: bool = False, interface_version: Optional[str] = None) -
-
-

Definition of an Mbed Enabled Device.

-

An Mbed Device is always a USB mass storage device, which sometimes also presents a USB serial port. -A valid Mbed Device must have a Board associated with it.

-

Attributes

-
-
mbed_board
-
The Board associated with this device.
-
serial_number
-
The serial number presented by the device to the USB subsystem.
-
serial_port
-
The serial port presented by this device, could be None.
-
mount_points
-
The filesystem mount points associated with this device.
-
-
- -Expand source code - -
class Device:
-    """Definition of an Mbed Enabled Device.
-
-    An Mbed Device is always a USB mass storage device, which sometimes also presents a USB serial port.
-    A valid Mbed Device must have a Board associated with it.
-
-    Attributes:
-        mbed_board: The Board associated with this device.
-        serial_number: The serial number presented by the device to the USB subsystem.
-        serial_port: The serial port presented by this device, could be None.
-        mount_points: The filesystem mount points associated with this device.
-    """
-
-    mbed_board: Board
-    serial_number: str
-    serial_port: Optional[str]
-    mount_points: Tuple[Path, ...]
-    mbed_enabled: bool = False
-    interface_version: Optional[str] = None
-
-    @classmethod
-    def from_candidate(cls, candidate: CandidateDevice) -> "Device":
-        """Contruct a Device from a CandidateDevice.
-
-        We try to resolve a board using data files that may be stored on the CandidateDevice.
-        If this fails we set the board to `None` which means we couldn't verify this Device
-        as being an Mbed enabled device.
-
-        Args:
-            candidate: The CandidateDevice we're using to create the Device.
-        """
-        device_file_info = read_device_files(candidate.mount_points)
-        try:
-            mbed_board = resolve_board(
-                device_file_info.product_code, device_file_info.online_id, candidate.serial_number
-            )
-            mbed_enabled = True
-        except NoBoardForCandidate:
-            # Create an empty Board to ensure the device is fully populated and rendering is simple
-            mbed_board = Board.from_offline_board_entry({})
-            mbed_enabled = False
-        except ResolveBoardError:
-            raise DeviceLookupFailed(
-                f"Failed to resolve the board for candidate device {candidate!r}. There was a problem looking up the "
-                "board data in the database."
-            )
-
-        return Device(
-            serial_port=candidate.serial_port,
-            serial_number=candidate.serial_number,
-            mount_points=candidate.mount_points,
-            mbed_board=mbed_board,
-            mbed_enabled=mbed_enabled,
-            interface_version=device_file_info.interface_details.get("Version"),
-        )
-
-

Class variables

-
-
var interface_version : Optional[str]
-
-
-
-
var mbed_board : Board
-
-
-
-
var mbed_enabled : bool
-
-
-
-
var mount_points : Tuple[pathlib.Path, ...]
-
-
-
-
var serial_number : str
-
-
-
-
var serial_port : Optional[str]
-
-
-
-
-

Static methods

-
-
-def from_candidate(candidate: mbed_tools.devices._internal.candidate_device.CandidateDevice) ‑> Device -
-
-

Contruct a Device from a CandidateDevice.

-

We try to resolve a board using data files that may be stored on the CandidateDevice. -If this fails we set the board to None which means we couldn't verify this Device -as being an Mbed enabled device.

-

Args

-
-
candidate
-
The CandidateDevice we're using to create the Device.
-
-
- -Expand source code - -
@classmethod
-def from_candidate(cls, candidate: CandidateDevice) -> "Device":
-    """Contruct a Device from a CandidateDevice.
-
-    We try to resolve a board using data files that may be stored on the CandidateDevice.
-    If this fails we set the board to `None` which means we couldn't verify this Device
-    as being an Mbed enabled device.
-
-    Args:
-        candidate: The CandidateDevice we're using to create the Device.
-    """
-    device_file_info = read_device_files(candidate.mount_points)
-    try:
-        mbed_board = resolve_board(
-            device_file_info.product_code, device_file_info.online_id, candidate.serial_number
-        )
-        mbed_enabled = True
-    except NoBoardForCandidate:
-        # Create an empty Board to ensure the device is fully populated and rendering is simple
-        mbed_board = Board.from_offline_board_entry({})
-        mbed_enabled = False
-    except ResolveBoardError:
-        raise DeviceLookupFailed(
-            f"Failed to resolve the board for candidate device {candidate!r}. There was a problem looking up the "
-            "board data in the database."
-        )
-
-    return Device(
-        serial_port=candidate.serial_port,
-        serial_number=candidate.serial_number,
-        mount_points=candidate.mount_points,
-        mbed_board=mbed_board,
-        mbed_enabled=mbed_enabled,
-        interface_version=device_file_info.interface_details.get("Version"),
-    )
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/devices/devices.html b/docs/api/devices/devices.html deleted file mode 100644 index 5a17ffc3..00000000 --- a/docs/api/devices/devices.html +++ /dev/null @@ -1,310 +0,0 @@ - - - - - - -mbed_tools.devices.devices API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.devices.devices

-
-
-

API for listing devices.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""API for listing devices."""
-
-from operator import attrgetter
-from typing import List, Optional
-
-from mbed_tools.devices._internal.detect_candidate_devices import detect_candidate_devices
-
-from mbed_tools.devices.device import ConnectedDevices, Device
-from mbed_tools.devices.exceptions import DeviceLookupFailed, NoDevicesFound
-
-
-def get_connected_devices() -> ConnectedDevices:
-    """Returns Mbed Devices connected to host computer.
-
-    Connected devices which have been identified as Mbed Boards and also connected devices which are potentially
-    Mbed Boards (but not could not be identified in the database) are returned.
-    """
-    connected_devices = ConnectedDevices()
-
-    for candidate_device in detect_candidate_devices():
-        device = Device.from_candidate(candidate_device)
-        connected_devices.add_device(device)
-
-    return connected_devices
-
-
-def find_connected_device(target_name: str, identifier: Optional[int] = None) -> Device:
-    """Find a connected device matching the given target_name, if there is only one.
-
-    Args:
-        target_name: The Mbed target name of the device.
-        identifier: Where multiple of the same Mbed device are connected, the associated [id].
-
-    Raise:
-        DeviceLookupFailed: Could not find device matching target_name.
-
-    Returns:
-        The first Device found matching target_name.
-    """
-    devices = find_all_connected_devices(target_name)
-    if identifier is None and len(devices) == 1:
-        return devices[0]
-    elif identifier is not None and len(devices) > identifier:
-        return devices[identifier]
-
-    detected_targets = "\n".join(
-        f"target: {dev.mbed_board.board_type}[{i}]," f" port: {dev.serial_port}, mount point(s): {dev.mount_points}"
-        for i, dev in enumerate(devices)
-    )
-    if identifier is None:
-        msg = (
-            f"`Multiple matching, please select a connected target with [n] identifier.\n"
-            f"The following {target_name}s were detected:\n{detected_targets}"
-        )
-    else:
-        msg = (
-            f"`{target_name}[{identifier}]` is not a valid connected target.\n"
-            f"The following {target_name}s were detected:\n{detected_targets}"
-        )
-    raise DeviceLookupFailed(msg)
-
-
-def find_all_connected_devices(target_name: str) -> List[Device]:
-    """Find all connected devices matching the given target_name.
-
-    Args:
-        target_name: The Mbed target name of the device.
-
-    Raises:
-        NoDevicesFound: Could not find any connected devices.
-        DeviceLookupFailed: Could not find a connected device matching target_name.
-
-    Returns:
-        List of Devices matching target_name.
-    """
-    connected = get_connected_devices()
-    if not connected.identified_devices:
-        raise NoDevicesFound("No Mbed enabled devices found.")
-
-    matching_devices = sorted(
-        [device for device in connected.identified_devices if device.mbed_board.board_type == target_name.upper()],
-        key=attrgetter("serial_number"),
-    )
-    if matching_devices:
-        return matching_devices
-
-    detected_targets = "\n".join(
-        f"target: {dev.mbed_board.board_type}, port: {dev.serial_port}, mount point(s): {dev.mount_points}"
-        for dev in connected.identified_devices
-    )
-    msg = (
-        f"Target '{target_name}' was not detected.\n"
-        "Check the device is connected by USB, and that the name is entered correctly.\n"
-        f"The following devices were detected:\n{detected_targets}"
-    )
-    raise DeviceLookupFailed(msg)
-
-
-
-
-
-
-
-

Functions

-
-
-def find_all_connected_devices(target_name: str) ‑> List[Device] -
-
-

Find all connected devices matching the given target_name.

-

Args

-
-
target_name
-
The Mbed target name of the device.
-
-

Raises

-
-
NoDevicesFound
-
Could not find any connected devices.
-
DeviceLookupFailed
-
Could not find a connected device matching target_name.
-
-

Returns

-

List of Devices matching target_name.

-
- -Expand source code - -
def find_all_connected_devices(target_name: str) -> List[Device]:
-    """Find all connected devices matching the given target_name.
-
-    Args:
-        target_name: The Mbed target name of the device.
-
-    Raises:
-        NoDevicesFound: Could not find any connected devices.
-        DeviceLookupFailed: Could not find a connected device matching target_name.
-
-    Returns:
-        List of Devices matching target_name.
-    """
-    connected = get_connected_devices()
-    if not connected.identified_devices:
-        raise NoDevicesFound("No Mbed enabled devices found.")
-
-    matching_devices = sorted(
-        [device for device in connected.identified_devices if device.mbed_board.board_type == target_name.upper()],
-        key=attrgetter("serial_number"),
-    )
-    if matching_devices:
-        return matching_devices
-
-    detected_targets = "\n".join(
-        f"target: {dev.mbed_board.board_type}, port: {dev.serial_port}, mount point(s): {dev.mount_points}"
-        for dev in connected.identified_devices
-    )
-    msg = (
-        f"Target '{target_name}' was not detected.\n"
-        "Check the device is connected by USB, and that the name is entered correctly.\n"
-        f"The following devices were detected:\n{detected_targets}"
-    )
-    raise DeviceLookupFailed(msg)
-
-
-
-def find_connected_device(target_name: str, identifier: Optional[int] = None) ‑> Device -
-
-

Find a connected device matching the given target_name, if there is only one.

-

Args

-
-
target_name
-
The Mbed target name of the device.
-
identifier
-
Where multiple of the same Mbed device are connected, the associated [id].
-
-

Raise

-

DeviceLookupFailed: Could not find device matching target_name.

-

Returns

-

The first Device found matching target_name.

-
- -Expand source code - -
def find_connected_device(target_name: str, identifier: Optional[int] = None) -> Device:
-    """Find a connected device matching the given target_name, if there is only one.
-
-    Args:
-        target_name: The Mbed target name of the device.
-        identifier: Where multiple of the same Mbed device are connected, the associated [id].
-
-    Raise:
-        DeviceLookupFailed: Could not find device matching target_name.
-
-    Returns:
-        The first Device found matching target_name.
-    """
-    devices = find_all_connected_devices(target_name)
-    if identifier is None and len(devices) == 1:
-        return devices[0]
-    elif identifier is not None and len(devices) > identifier:
-        return devices[identifier]
-
-    detected_targets = "\n".join(
-        f"target: {dev.mbed_board.board_type}[{i}]," f" port: {dev.serial_port}, mount point(s): {dev.mount_points}"
-        for i, dev in enumerate(devices)
-    )
-    if identifier is None:
-        msg = (
-            f"`Multiple matching, please select a connected target with [n] identifier.\n"
-            f"The following {target_name}s were detected:\n{detected_targets}"
-        )
-    else:
-        msg = (
-            f"`{target_name}[{identifier}]` is not a valid connected target.\n"
-            f"The following {target_name}s were detected:\n{detected_targets}"
-        )
-    raise DeviceLookupFailed(msg)
-
-
-
-def get_connected_devices() ‑> ConnectedDevices -
-
-

Returns Mbed Devices connected to host computer.

-

Connected devices which have been identified as Mbed Boards and also connected devices which are potentially -Mbed Boards (but not could not be identified in the database) are returned.

-
- -Expand source code - -
def get_connected_devices() -> ConnectedDevices:
-    """Returns Mbed Devices connected to host computer.
-
-    Connected devices which have been identified as Mbed Boards and also connected devices which are potentially
-    Mbed Boards (but not could not be identified in the database) are returned.
-    """
-    connected_devices = ConnectedDevices()
-
-    for candidate_device in detect_candidate_devices():
-        device = Device.from_candidate(candidate_device)
-        connected_devices.add_device(device)
-
-    return connected_devices
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/devices/exceptions.html b/docs/api/devices/exceptions.html deleted file mode 100644 index 05ea3c5a..00000000 --- a/docs/api/devices/exceptions.html +++ /dev/null @@ -1,189 +0,0 @@ - - - - - - -mbed_tools.devices.exceptions API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.devices.exceptions

-
-
-

Public exceptions raised by the package.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Public exceptions raised by the package."""
-from mbed_tools.lib.exceptions import ToolsError
-
-
-class MbedDevicesError(ToolsError):
-    """Base public exception for the mbed-devices package."""
-
-
-class DeviceLookupFailed(MbedDevicesError):
-    """Failed to look up data associated with the device."""
-
-
-class NoDevicesFound(MbedDevicesError):
-    """No Mbed Enabled devices were found."""
-
-
-class UnknownOSError(MbedDevicesError):
-    """The current OS is not supported."""
-
-
-
-
-
-
-
-
-
-

Classes

-
-
-class DeviceLookupFailed -(*args, **kwargs) -
-
-

Failed to look up data associated with the device.

-
- -Expand source code - -
class DeviceLookupFailed(MbedDevicesError):
-    """Failed to look up data associated with the device."""
-
-

Ancestors

- -
-
-class MbedDevicesError -(*args, **kwargs) -
-
-

Base public exception for the mbed-devices package.

-
- -Expand source code - -
class MbedDevicesError(ToolsError):
-    """Base public exception for the mbed-devices package."""
-
-

Ancestors

-
    -
  • ToolsError
    • -
  • builtins.Exception
    • -
  • builtins.BaseException
    • -
-

Subclasses

- -
-
-class NoDevicesFound -(*args, **kwargs) -
-
-

No Mbed Enabled devices were found.

-
- -Expand source code - -
class NoDevicesFound(MbedDevicesError):
-    """No Mbed Enabled devices were found."""
-
-

Ancestors

- -
-
-class UnknownOSError -(*args, **kwargs) -
-
-

The current OS is not supported.

-
- -Expand source code - -
class UnknownOSError(MbedDevicesError):
-    """The current OS is not supported."""
-
-

Ancestors

- -
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/devices/index.html b/docs/api/devices/index.html deleted file mode 100644 index 768eb5d4..00000000 --- a/docs/api/devices/index.html +++ /dev/null @@ -1,104 +0,0 @@ - - - - - - -mbed_tools.devices API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.devices

-
-
-

API to detect any Mbed OS devices connected to the host computer.

-

It is expected that this package will be used by developers of Mbed OS tooling rather than by users of Mbed OS. -This package uses the https://github.com/ARMmbed/mbed-targets interface to identify valid Mbed Enabled Devices. -Please see the documentation for mbed-targets for information on configuration options.

-

For the command line interface to the API see the package https://github.com/ARMmbed/mbed-tools

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""API to detect any Mbed OS devices connected to the host computer.
-
-It is expected that this package will be used by developers of Mbed OS tooling rather than by users of Mbed OS.
-This package uses the https://github.com/ARMmbed/mbed-targets interface to identify valid Mbed Enabled Devices.
-Please see the documentation for mbed-targets for information on configuration options.
-
-For the command line interface to the API see the package https://github.com/ARMmbed/mbed-tools
-"""
-from mbed_tools.devices.devices import (
-    get_connected_devices,
-    find_connected_device,
-    find_all_connected_devices,
-)
-from mbed_tools.devices.device import Device
-from mbed_tools.devices import exceptions
-
-
-
-

Sub-modules

-
-
mbed_tools.devices.device
-
-

Data model definition for Device and ConnectedDevices.

-
-
mbed_tools.devices.devices
-
-

API for listing devices.

-
-
mbed_tools.devices.exceptions
-
-

Public exceptions raised by the package.

-
-
-
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/index.html b/docs/api/index.html deleted file mode 100644 index 67895bec..00000000 --- a/docs/api/index.html +++ /dev/null @@ -1,101 +0,0 @@ - - - - - - -mbed_tools API documentation - - - - - - - - - - - -
-
-
-

Package mbed_tools

-
-
-

Exposes the primary interfaces for the library.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Exposes the primary interfaces for the library."""
-
-
-
-

Sub-modules

-
-
mbed_tools.build
-
-

Provides the core build system for Mbed OS, which relies on CMake and Ninja as underlying technologies …

-
-
mbed_tools.cli
-
-

mbed_tools command line interface.

-
-
mbed_tools.devices
-
-

API to detect any Mbed OS devices connected to the host computer …

-
-
mbed_tools.lib
-
-

Provides a library of common code.

-
-
mbed_tools.project
-
-

Creation and management of Mbed OS projects …

-
-
mbed_tools.sterm
-
-

Package containing sterm functionality.

-
-
mbed_tools.targets
-
-

An abstraction layer describing hardware supported by Mbed OS …

-
-
-
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/lib/exceptions.html b/docs/api/lib/exceptions.html deleted file mode 100644 index 637deed8..00000000 --- a/docs/api/lib/exceptions.html +++ /dev/null @@ -1,109 +0,0 @@ - - - - - - -mbed_tools.lib.exceptions API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.lib.exceptions

-
-
-

Exceptions raised by mbed tools.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Exceptions raised by mbed tools."""
-
-
-class ToolsError(Exception):
-    """Base class for tools errors."""
-
-
-
-
-
-
-
-
-
-

Classes

-
-
-class ToolsError -(*args, **kwargs) -
-
-

Base class for tools errors.

-
- -Expand source code - -
class ToolsError(Exception):
-    """Base class for tools errors."""
-
-

Ancestors

-
    -
  • builtins.Exception
    • -
  • builtins.BaseException
    • -
-

Subclasses

- -
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/lib/index.html b/docs/api/lib/index.html deleted file mode 100644 index d2e282f0..00000000 --- a/docs/api/lib/index.html +++ /dev/null @@ -1,91 +0,0 @@ - - - - - - -mbed_tools.lib API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.lib

-
-
-

Provides a library of common code.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Provides a library of common code."""
-
-
-
-

Sub-modules

-
-
mbed_tools.lib.exceptions
-
-

Exceptions raised by mbed tools.

-
-
mbed_tools.lib.json_helpers
-
-

Helpers for json related functions.

-
-
mbed_tools.lib.logging
-
-

Helpers for logging errors according to severity of the exception.

-
-
mbed_tools.lib.python_helpers
-
-

Helpers for python language related functions.

-
-
-
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/lib/json_helpers.html b/docs/api/lib/json_helpers.html deleted file mode 100644 index 72d34f09..00000000 --- a/docs/api/lib/json_helpers.html +++ /dev/null @@ -1,108 +0,0 @@ - - - - - - -mbed_tools.lib.json_helpers API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.lib.json_helpers

-
-
-

Helpers for json related functions.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Helpers for json related functions."""
-import json
-import logging
-
-from pathlib import Path
-from typing import Any
-
-logger = logging.getLogger(__name__)
-
-
-def decode_json_file(path: Path) -> Any:
-    """Return the contents of json file."""
-    try:
-        logger.debug(f"Loading JSON file {path}")
-        return json.loads(path.read_text())
-    except json.JSONDecodeError:
-        logger.error(f"Failed to decode JSON data in the file located at '{path}'")
-        raise
-
-
-
-
-
-
-
-

Functions

-
-
-def decode_json_file(path: pathlib.Path) ‑> Any -
-
-

Return the contents of json file.

-
- -Expand source code - -
def decode_json_file(path: Path) -> Any:
-    """Return the contents of json file."""
-    try:
-        logger.debug(f"Loading JSON file {path}")
-        return json.loads(path.read_text())
-    except json.JSONDecodeError:
-        logger.error(f"Failed to decode JSON data in the file located at '{path}'")
-        raise
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/lib/logging.html b/docs/api/lib/logging.html deleted file mode 100644 index 7b1aa5f4..00000000 --- a/docs/api/lib/logging.html +++ /dev/null @@ -1,267 +0,0 @@ - - - - - - -mbed_tools.lib.logging API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.lib.logging

-
-
-

Helpers for logging errors according to severity of the exception.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Helpers for logging errors according to severity of the exception."""
-from typing import Type, Optional, cast
-from types import TracebackType
-import logging
-from mbed_tools.lib.exceptions import ToolsError
-
-LOGGING_FORMAT = "%(levelname)s: %(message)s"
-
-VERBOSITY_HELP = {
-    logging.CRITICAL: "-v",
-    logging.ERROR: "-v",
-    logging.WARNING: "-vv",
-    logging.INFO: "-vvv",
-    logging.DEBUG: "--traceback",
-}
-
-
-def _exception_message(err: BaseException, log_level: int, traceback: bool) -> str:
-    """Generate a user facing message with help on how to get more information from the logs."""
-    error_msg = str(err)
-    if log_level != logging.DEBUG or not traceback:
-        cli_option = VERBOSITY_HELP.get(log_level, "-v")
-        error_msg += f"\n\nMore information may be available by using the command line option '{cli_option}'."
-    return error_msg
-
-
-class MbedToolsHandler:
-    """Context Manager to catch Mbed Tools exceptions and generate a helpful user facing message."""
-
-    def __init__(self, logger: logging.Logger, traceback: bool = False):
-        """Keep track of the logger to use and whether or not a traceback should be generated."""
-        self._logger = logger
-        self._traceback = traceback
-        self.exit_code = 0
-
-    def __enter__(self) -> "MbedToolsHandler":
-        """Return the Context Manager."""
-        return self
-
-    def __exit__(
-        self,
-        exc_type: Optional[Type[BaseException]],
-        exc_value: Optional[BaseException],
-        exc_traceback: Optional[TracebackType],
-    ) -> bool:
-        """Handle any raised exceptions, suppressing Tools errors and generating an error message instead."""
-        if exc_type and issubclass(exc_type, ToolsError):
-            error_msg = _exception_message(cast(BaseException, exc_value), logging.root.level, self._traceback)
-            self._logger.error(error_msg, exc_info=self._traceback)
-            # Do not propagate exceptions derived from ToolsError
-            self.exit_code = 1
-            return True
-
-        # Propagate all other exceptions
-        return False
-
-
-def log_exception(logger: logging.Logger, exception: Exception, show_traceback: bool = False) -> None:
-    """Logs an exception in both normal and verbose forms.
-
-    Args:
-        logger: logger
-        exception: exception to log
-        show_traceback: show the full traceback.
-    """
-    logger.error(exception, exc_info=show_traceback)
-
-
-def set_log_level(verbose_count: int) -> None:
-    """Sets the log level.
-
-    Args:
-        verbose_count: number of `-v` flags used
-    """
-    if verbose_count > 2:
-        log_level = logging.DEBUG
-    elif verbose_count == 2:
-        log_level = logging.INFO
-    elif verbose_count == 1:
-        log_level = logging.WARNING
-    else:
-        log_level = logging.ERROR
-    logging.basicConfig(level=log_level, format=LOGGING_FORMAT)
-
-
-
-
-
-
-
-

Functions

-
-
-def log_exception(logger: logging.Logger, exception: Exception, show_traceback: bool = False) ‑> None -
-
-

Logs an exception in both normal and verbose forms.

-

Args

-
-
logger
-
logger
-
exception
-
exception to log
-
show_traceback
-
show the full traceback.
-
-
- -Expand source code - -
def log_exception(logger: logging.Logger, exception: Exception, show_traceback: bool = False) -> None:
-    """Logs an exception in both normal and verbose forms.
-
-    Args:
-        logger: logger
-        exception: exception to log
-        show_traceback: show the full traceback.
-    """
-    logger.error(exception, exc_info=show_traceback)
-
-
-
-def set_log_level(verbose_count: int) ‑> None -
-
-

Sets the log level.

-

Args

-
-
verbose_count
-
number of -v flags used
-
-
- -Expand source code - -
def set_log_level(verbose_count: int) -> None:
-    """Sets the log level.
-
-    Args:
-        verbose_count: number of `-v` flags used
-    """
-    if verbose_count > 2:
-        log_level = logging.DEBUG
-    elif verbose_count == 2:
-        log_level = logging.INFO
-    elif verbose_count == 1:
-        log_level = logging.WARNING
-    else:
-        log_level = logging.ERROR
-    logging.basicConfig(level=log_level, format=LOGGING_FORMAT)
-
-
-
-
-
-

Classes

-
-
-class MbedToolsHandler -(logger: logging.Logger, traceback: bool = False) -
-
-

Context Manager to catch Mbed Tools exceptions and generate a helpful user facing message.

-

Keep track of the logger to use and whether or not a traceback should be generated.

-
- -Expand source code - -
class MbedToolsHandler:
-    """Context Manager to catch Mbed Tools exceptions and generate a helpful user facing message."""
-
-    def __init__(self, logger: logging.Logger, traceback: bool = False):
-        """Keep track of the logger to use and whether or not a traceback should be generated."""
-        self._logger = logger
-        self._traceback = traceback
-        self.exit_code = 0
-
-    def __enter__(self) -> "MbedToolsHandler":
-        """Return the Context Manager."""
-        return self
-
-    def __exit__(
-        self,
-        exc_type: Optional[Type[BaseException]],
-        exc_value: Optional[BaseException],
-        exc_traceback: Optional[TracebackType],
-    ) -> bool:
-        """Handle any raised exceptions, suppressing Tools errors and generating an error message instead."""
-        if exc_type and issubclass(exc_type, ToolsError):
-            error_msg = _exception_message(cast(BaseException, exc_value), logging.root.level, self._traceback)
-            self._logger.error(error_msg, exc_info=self._traceback)
-            # Do not propagate exceptions derived from ToolsError
-            self.exit_code = 1
-            return True
-
-        # Propagate all other exceptions
-        return False
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/lib/python_helpers.html b/docs/api/lib/python_helpers.html deleted file mode 100644 index 1d6134bb..00000000 --- a/docs/api/lib/python_helpers.html +++ /dev/null @@ -1,135 +0,0 @@ - - - - - - -mbed_tools.lib.python_helpers API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.lib.python_helpers

-
-
-

Helpers for python language related functions.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Helpers for python language related functions."""
-from typing import Iterable, List
-
-
-def flatten_nested(input_iter: Iterable) -> List:
-    """Flatten a nested Iterable with arbitrary levels of nesting.
-
-    If the input is an iterator then this function will exhaust it.
-
-    Args:
-        input_iter: The input Iterable which may or may not be nested.
-
-    Returns:
-        A flat list created from the input_iter.
-        If input_iter has no nesting its elements are appended to a list and returned.
-    """
-    output = []
-    for elem in input_iter:
-        if isinstance(elem, Iterable) and not isinstance(elem, str):
-            output += flatten_nested(elem)
-        else:
-            output.append(elem)
-
-    return output
-
-
-
-
-
-
-
-

Functions

-
-
-def flatten_nested(input_iter: Iterable[+T_co]) ‑> List[~T] -
-
-

Flatten a nested Iterable with arbitrary levels of nesting.

-

If the input is an iterator then this function will exhaust it.

-

Args

-
-
input_iter
-
The input Iterable which may or may not be nested.
-
-

Returns

-

A flat list created from the input_iter. -If input_iter has no nesting its elements are appended to a list and returned.

-
- -Expand source code - -
def flatten_nested(input_iter: Iterable) -> List:
-    """Flatten a nested Iterable with arbitrary levels of nesting.
-
-    If the input is an iterator then this function will exhaust it.
-
-    Args:
-        input_iter: The input Iterable which may or may not be nested.
-
-    Returns:
-        A flat list created from the input_iter.
-        If input_iter has no nesting its elements are appended to a list and returned.
-    """
-    output = []
-    for elem in input_iter:
-        if isinstance(elem, Iterable) and not isinstance(elem, str):
-            output += flatten_nested(elem)
-        else:
-            output.append(elem)
-
-    return output
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/project/exceptions.html b/docs/api/project/exceptions.html deleted file mode 100644 index 6428d709..00000000 --- a/docs/api/project/exceptions.html +++ /dev/null @@ -1,219 +0,0 @@ - - - - - - -mbed_tools.project.exceptions API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.project.exceptions

-
-
-

Public exceptions exposed by the package.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Public exceptions exposed by the package."""
-
-from mbed_tools.lib.exceptions import ToolsError
-
-
-class MbedProjectError(ToolsError):
-    """Base exception for mbed-project."""
-
-
-class VersionControlError(MbedProjectError):
-    """Raised when a source control management operation failed."""
-
-
-class ExistingProgram(MbedProjectError):
-    """Raised when a program already exists at a given path."""
-
-
-class ProgramNotFound(MbedProjectError):
-    """Raised when an expected program is not found."""
-
-
-class MbedOSNotFound(MbedProjectError):
-    """A valid copy of MbedOS was not found."""
-
-
-
-
-
-
-
-
-
-

Classes

-
-
-class ExistingProgram -(*args, **kwargs) -
-
-

Raised when a program already exists at a given path.

-
- -Expand source code - -
class ExistingProgram(MbedProjectError):
-    """Raised when a program already exists at a given path."""
-
-

Ancestors

- -
-
-class MbedOSNotFound -(*args, **kwargs) -
-
-

A valid copy of MbedOS was not found.

-
- -Expand source code - -
class MbedOSNotFound(MbedProjectError):
-    """A valid copy of MbedOS was not found."""
-
-

Ancestors

- -
-
-class MbedProjectError -(*args, **kwargs) -
-
-

Base exception for mbed-project.

-
- -Expand source code - -
class MbedProjectError(ToolsError):
-    """Base exception for mbed-project."""
-
-

Ancestors

-
    -
  • ToolsError
    • -
  • builtins.Exception
    • -
  • builtins.BaseException
    • -
-

Subclasses

- -
-
-class ProgramNotFound -(*args, **kwargs) -
-
-

Raised when an expected program is not found.

-
- -Expand source code - -
class ProgramNotFound(MbedProjectError):
-    """Raised when an expected program is not found."""
-
-

Ancestors

- -
-
-class VersionControlError -(*args, **kwargs) -
-
-

Raised when a source control management operation failed.

-
- -Expand source code - -
class VersionControlError(MbedProjectError):
-    """Raised when a source control management operation failed."""
-
-

Ancestors

- -
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/project/index.html b/docs/api/project/index.html deleted file mode 100644 index 72677473..00000000 --- a/docs/api/project/index.html +++ /dev/null @@ -1,99 +0,0 @@ - - - - - - -mbed_tools.project API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.project

-
-
-

Creation and management of Mbed OS projects.

-
    -
  • Creation of a new Mbed OS application.
    • -
  • Cloning of an existing Mbed OS program.
    • -
  • Deploy of a specific version of Mbed OS or library.
    • -
-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Creation and management of Mbed OS projects.
-
-* Creation of a new Mbed OS application.
-* Cloning of an existing Mbed OS program.
-* Deploy of a specific version of Mbed OS or library.
-"""
-
-from mbed_tools.project.project import initialise_project, import_project, deploy_project, get_known_libs
-from mbed_tools.project.mbed_program import MbedProgram
-
-
-
-

Sub-modules

-
-
mbed_tools.project.exceptions
-
-

Public exceptions exposed by the package.

-
-
mbed_tools.project.mbed_program
-
-

Mbed Program abstraction layer.

-
-
mbed_tools.project.project
-
-

Defines the public API of the package.

-
-
-
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/project/mbed_program.html b/docs/api/project/mbed_program.html deleted file mode 100644 index 82393ba6..00000000 --- a/docs/api/project/mbed_program.html +++ /dev/null @@ -1,503 +0,0 @@ - - - - - - -mbed_tools.project.mbed_program API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.project.mbed_program

-
-
-

Mbed Program abstraction layer.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Mbed Program abstraction layer."""
-import logging
-
-from pathlib import Path
-from typing import Dict
-from urllib.parse import urlparse
-
-from mbed_tools.project.exceptions import ProgramNotFound, ExistingProgram, MbedOSNotFound
-from mbed_tools.project._internal.project_data import (
-    MbedProgramFiles,
-    MbedOS,
-    MBED_OS_REFERENCE_FILE_NAME,
-    MBED_OS_DIR_NAME,
-)
-
-logger = logging.getLogger(__name__)
-
-
-class MbedProgram:
-    """Represents an Mbed program.
-
-    An `MbedProgram` consists of:
-        * A copy of, or reference to, `MbedOS`
-        * A set of `MbedProgramFiles`
-        * A collection of references to external libraries, defined in .lib files located in the program source tree
-    """
-
-    def __init__(self, program_files: MbedProgramFiles, mbed_os: MbedOS) -> None:
-        """Initialise the program attributes.
-
-        Args:
-            program_files: Object holding paths to a set of files that define an Mbed program.
-            mbed_os: An instance of `MbedOS` holding paths to locations in the local copy of the Mbed OS source.
-        """
-        self.files = program_files
-        self.root = self.files.mbed_os_ref.parent
-        self.mbed_os = mbed_os
-
-    @classmethod
-    def from_new(cls, dir_path: Path) -> "MbedProgram":
-        """Create an MbedProgram from an empty directory.
-
-        Creates the directory if it doesn't exist.
-
-        Args:
-            dir_path: Directory in which to create the program.
-
-        Raises:
-            ExistingProgram: An existing program was found in the path.
-        """
-        if _tree_contains_program(dir_path):
-            raise ExistingProgram(
-                f"An existing Mbed program was found in the directory tree {dir_path}. It is not possible to nest Mbed "
-                "programs. Please ensure there is no mbed-os.lib file in the cwd hierarchy."
-            )
-
-        logger.info(f"Creating Mbed program at path '{dir_path.resolve()}'")
-        dir_path.mkdir(exist_ok=True)
-        program_files = MbedProgramFiles.from_new(dir_path)
-        logger.info(f"Creating git repository for the Mbed program '{dir_path}'")
-        mbed_os = MbedOS.from_new(dir_path / MBED_OS_DIR_NAME)
-        return cls(program_files, mbed_os)
-
-    @classmethod
-    def from_existing(
-        cls, dir_path: Path, build_subdir: Path, mbed_os_path: Path = None, check_mbed_os: bool = True,
-    ) -> "MbedProgram":
-        """Create an MbedProgram from an existing program directory.
-
-        Args:
-            dir_path: Directory containing an Mbed program.
-            build_subdir: The subdirectory for the CMake build tree.
-            mbed_os_path: Directory containing Mbed OS.
-            check_mbed_os: If True causes an exception to be raised if the Mbed OS source directory does not
-                           exist.
-
-        Raises:
-            ProgramNotFound: An existing program was not found in the path.
-        """
-        if mbed_os_path is None:
-            program_root = _find_program_root(dir_path)
-            mbed_os_path = program_root / MBED_OS_DIR_NAME
-        else:
-            program_root = dir_path
-
-        logger.info(f"Found existing Mbed program at path '{program_root}'")
-        program = MbedProgramFiles.from_existing(program_root, build_subdir)
-
-        try:
-            mbed_os = MbedOS.from_existing(mbed_os_path, check_mbed_os)
-        except ValueError as mbed_os_err:
-            raise MbedOSNotFound(
-                f"Mbed OS was not found due to the following error: {mbed_os_err}"
-                "\nYou may need to resolve the mbed-os.lib reference. You can do this by performing a `deploy`."
-            )
-
-        return cls(program, mbed_os)
-
-
-def parse_url(name_or_url: str) -> Dict[str, str]:
-    """Create a valid github/armmbed url from a program name.
-
-    Args:
-        url: The URL, or a program name to turn into an URL.
-
-    Returns:
-        Dictionary containing the remote url and the destination path for the clone.
-    """
-    url_obj = urlparse(name_or_url)
-    if url_obj.hostname:
-        url = url_obj.geturl()
-    elif ":" in name_or_url.split("/", maxsplit=1)[0]:
-        # If non-standard and no slashes before first colon, git will recognize as scp ssh syntax
-        url = name_or_url
-    else:
-        url = f"https://github.com/armmbed/{url_obj.path}"
-    # We need to create a valid directory name from the url path section.
-    return {"url": url, "dst_path": url_obj.path.rsplit("/", maxsplit=1)[-1].replace("/", "")}
-
-
-def _tree_contains_program(path: Path) -> bool:
-    """Check if the current path or its ancestors contain an mbed-os.lib file.
-
-    Args:
-        path: The starting path for the search. The search walks up the tree from this path.
-
-    Returns:
-        `True` if an mbed-os.lib file is located between `path` and filesystem root.
-        `False` if no mbed-os.lib file was found.
-    """
-    try:
-        _find_program_root(path)
-        return True
-    except ProgramNotFound:
-        return False
-
-
-def _find_program_root(cwd: Path) -> Path:
-    """Walk up the directory tree, looking for an mbed-os.lib file.
-
-    Programs contain an mbed-os.lib file at the root of the source tree.
-
-    Args:
-        cwd: The directory path to search for a program.
-
-    Raises:
-        ProgramNotFound: No mbed-os.lib file found in the path.
-
-    Returns:
-        Path containing the mbed-os.lib file.
-    """
-    potential_root = cwd.absolute().resolve()
-    while str(potential_root) != str(potential_root.anchor):
-        logger.debug(f"Searching for mbed-os.lib file at path {potential_root}")
-        root_file = potential_root / MBED_OS_REFERENCE_FILE_NAME
-        if root_file.exists() and root_file.is_file():
-            logger.debug(f"mbed-os.lib file found at {potential_root}")
-            return potential_root
-
-        potential_root = potential_root.parent
-
-    logger.debug("No mbed-os.lib file found.")
-    raise ProgramNotFound(
-        f"No program found from {cwd.resolve()} to {cwd.resolve().anchor}. Please set the directory to a program "
-        "directory containing an mbed-os.lib file. You can also set the directory to a program subdirectory if there "
-        "is an mbed-os.lib file at the root of your program's directory tree."
-    )
-
-
-
-
-
-
-
-

Functions

-
-
-def parse_url(name_or_url: str) ‑> Dict[str, str] -
-
-

Create a valid github/armmbed url from a program name.

-

Args

-
-
url
-
The URL, or a program name to turn into an URL.
-
-

Returns

-

Dictionary containing the remote url and the destination path for the clone.

-
- -Expand source code - -
def parse_url(name_or_url: str) -> Dict[str, str]:
-    """Create a valid github/armmbed url from a program name.
-
-    Args:
-        url: The URL, or a program name to turn into an URL.
-
-    Returns:
-        Dictionary containing the remote url and the destination path for the clone.
-    """
-    url_obj = urlparse(name_or_url)
-    if url_obj.hostname:
-        url = url_obj.geturl()
-    elif ":" in name_or_url.split("/", maxsplit=1)[0]:
-        # If non-standard and no slashes before first colon, git will recognize as scp ssh syntax
-        url = name_or_url
-    else:
-        url = f"https://github.com/armmbed/{url_obj.path}"
-    # We need to create a valid directory name from the url path section.
-    return {"url": url, "dst_path": url_obj.path.rsplit("/", maxsplit=1)[-1].replace("/", "")}
-
-
-
-
-
-

Classes

-
-
-class MbedProgram -(program_files: mbed_tools.project._internal.project_data.MbedProgramFiles, mbed_os: mbed_tools.project._internal.project_data.MbedOS) -
-
-

Represents an Mbed program.

-

An MbedProgram consists of: -* A copy of, or reference to, MbedOS -* A set of MbedProgramFiles -* A collection of references to external libraries, defined in .lib files located in the program source tree

-

Initialise the program attributes.

-

Args

-
-
program_files
-
Object holding paths to a set of files that define an Mbed program.
-
mbed_os
-
An instance of MbedOS holding paths to locations in the local copy of the Mbed OS source.
-
-
- -Expand source code - -
class MbedProgram:
-    """Represents an Mbed program.
-
-    An `MbedProgram` consists of:
-        * A copy of, or reference to, `MbedOS`
-        * A set of `MbedProgramFiles`
-        * A collection of references to external libraries, defined in .lib files located in the program source tree
-    """
-
-    def __init__(self, program_files: MbedProgramFiles, mbed_os: MbedOS) -> None:
-        """Initialise the program attributes.
-
-        Args:
-            program_files: Object holding paths to a set of files that define an Mbed program.
-            mbed_os: An instance of `MbedOS` holding paths to locations in the local copy of the Mbed OS source.
-        """
-        self.files = program_files
-        self.root = self.files.mbed_os_ref.parent
-        self.mbed_os = mbed_os
-
-    @classmethod
-    def from_new(cls, dir_path: Path) -> "MbedProgram":
-        """Create an MbedProgram from an empty directory.
-
-        Creates the directory if it doesn't exist.
-
-        Args:
-            dir_path: Directory in which to create the program.
-
-        Raises:
-            ExistingProgram: An existing program was found in the path.
-        """
-        if _tree_contains_program(dir_path):
-            raise ExistingProgram(
-                f"An existing Mbed program was found in the directory tree {dir_path}. It is not possible to nest Mbed "
-                "programs. Please ensure there is no mbed-os.lib file in the cwd hierarchy."
-            )
-
-        logger.info(f"Creating Mbed program at path '{dir_path.resolve()}'")
-        dir_path.mkdir(exist_ok=True)
-        program_files = MbedProgramFiles.from_new(dir_path)
-        logger.info(f"Creating git repository for the Mbed program '{dir_path}'")
-        mbed_os = MbedOS.from_new(dir_path / MBED_OS_DIR_NAME)
-        return cls(program_files, mbed_os)
-
-    @classmethod
-    def from_existing(
-        cls, dir_path: Path, build_subdir: Path, mbed_os_path: Path = None, check_mbed_os: bool = True,
-    ) -> "MbedProgram":
-        """Create an MbedProgram from an existing program directory.
-
-        Args:
-            dir_path: Directory containing an Mbed program.
-            build_subdir: The subdirectory for the CMake build tree.
-            mbed_os_path: Directory containing Mbed OS.
-            check_mbed_os: If True causes an exception to be raised if the Mbed OS source directory does not
-                           exist.
-
-        Raises:
-            ProgramNotFound: An existing program was not found in the path.
-        """
-        if mbed_os_path is None:
-            program_root = _find_program_root(dir_path)
-            mbed_os_path = program_root / MBED_OS_DIR_NAME
-        else:
-            program_root = dir_path
-
-        logger.info(f"Found existing Mbed program at path '{program_root}'")
-        program = MbedProgramFiles.from_existing(program_root, build_subdir)
-
-        try:
-            mbed_os = MbedOS.from_existing(mbed_os_path, check_mbed_os)
-        except ValueError as mbed_os_err:
-            raise MbedOSNotFound(
-                f"Mbed OS was not found due to the following error: {mbed_os_err}"
-                "\nYou may need to resolve the mbed-os.lib reference. You can do this by performing a `deploy`."
-            )
-
-        return cls(program, mbed_os)
-
-

Static methods

-
-
-def from_existing(dir_path: pathlib.Path, build_subdir: pathlib.Path, mbed_os_path: pathlib.Path = None, check_mbed_os: bool = True) ‑> MbedProgram -
-
-

Create an MbedProgram from an existing program directory.

-

Args

-
-
dir_path
-
Directory containing an Mbed program.
-
build_subdir
-
The subdirectory for the CMake build tree.
-
mbed_os_path
-
Directory containing Mbed OS.
-
check_mbed_os
-
If True causes an exception to be raised if the Mbed OS source directory does not -exist.
-
-

Raises

-
-
ProgramNotFound
-
An existing program was not found in the path.
-
-
- -Expand source code - -
@classmethod
-def from_existing(
-    cls, dir_path: Path, build_subdir: Path, mbed_os_path: Path = None, check_mbed_os: bool = True,
-) -> "MbedProgram":
-    """Create an MbedProgram from an existing program directory.
-
-    Args:
-        dir_path: Directory containing an Mbed program.
-        build_subdir: The subdirectory for the CMake build tree.
-        mbed_os_path: Directory containing Mbed OS.
-        check_mbed_os: If True causes an exception to be raised if the Mbed OS source directory does not
-                       exist.
-
-    Raises:
-        ProgramNotFound: An existing program was not found in the path.
-    """
-    if mbed_os_path is None:
-        program_root = _find_program_root(dir_path)
-        mbed_os_path = program_root / MBED_OS_DIR_NAME
-    else:
-        program_root = dir_path
-
-    logger.info(f"Found existing Mbed program at path '{program_root}'")
-    program = MbedProgramFiles.from_existing(program_root, build_subdir)
-
-    try:
-        mbed_os = MbedOS.from_existing(mbed_os_path, check_mbed_os)
-    except ValueError as mbed_os_err:
-        raise MbedOSNotFound(
-            f"Mbed OS was not found due to the following error: {mbed_os_err}"
-            "\nYou may need to resolve the mbed-os.lib reference. You can do this by performing a `deploy`."
-        )
-
-    return cls(program, mbed_os)
-
-
-
-def from_new(dir_path: pathlib.Path) ‑> MbedProgram -
-
-

Create an MbedProgram from an empty directory.

-

Creates the directory if it doesn't exist.

-

Args

-
-
dir_path
-
Directory in which to create the program.
-
-

Raises

-
-
ExistingProgram
-
An existing program was found in the path.
-
-
- -Expand source code - -
@classmethod
-def from_new(cls, dir_path: Path) -> "MbedProgram":
-    """Create an MbedProgram from an empty directory.
-
-    Creates the directory if it doesn't exist.
-
-    Args:
-        dir_path: Directory in which to create the program.
-
-    Raises:
-        ExistingProgram: An existing program was found in the path.
-    """
-    if _tree_contains_program(dir_path):
-        raise ExistingProgram(
-            f"An existing Mbed program was found in the directory tree {dir_path}. It is not possible to nest Mbed "
-            "programs. Please ensure there is no mbed-os.lib file in the cwd hierarchy."
-        )
-
-    logger.info(f"Creating Mbed program at path '{dir_path.resolve()}'")
-    dir_path.mkdir(exist_ok=True)
-    program_files = MbedProgramFiles.from_new(dir_path)
-    logger.info(f"Creating git repository for the Mbed program '{dir_path}'")
-    mbed_os = MbedOS.from_new(dir_path / MBED_OS_DIR_NAME)
-    return cls(program_files, mbed_os)
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/project/project.html b/docs/api/project/project.html deleted file mode 100644 index 42a62923..00000000 --- a/docs/api/project/project.html +++ /dev/null @@ -1,297 +0,0 @@ - - - - - - -mbed_tools.project.project API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.project.project

-
-
-

Defines the public API of the package.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Defines the public API of the package."""
-import pathlib
-import logging
-
-from typing import List, Any
-
-from mbed_tools.project.mbed_program import MbedProgram, parse_url
-from mbed_tools.project._internal.libraries import LibraryReferences
-from mbed_tools.project._internal import git_utils
-
-logger = logging.getLogger(__name__)
-
-
-def import_project(url: str, dst_path: Any = None, recursive: bool = False) -> pathlib.Path:
-    """Clones an Mbed project from a remote repository.
-
-    Args:
-        url: URL of the repository to clone.
-        dst_path: Destination path for the repository.
-        recursive: Recursively clone all project dependencies.
-
-    Returns:
-        The path the project was cloned to.
-    """
-    git_data = parse_url(url)
-    url = git_data["url"]
-    if not dst_path:
-        dst_path = pathlib.Path(git_data["dst_path"])
-
-    git_utils.clone(url, dst_path)
-    if recursive:
-        libs = LibraryReferences(root=dst_path, ignore_paths=["mbed-os"])
-        libs.fetch()
-
-    return dst_path
-
-
-def initialise_project(path: pathlib.Path, create_only: bool) -> None:
-    """Create a new Mbed project, optionally fetching and adding mbed-os.
-
-    Args:
-        path: Path to the project folder. Created if it doesn't exist.
-        create_only: Flag which suppreses fetching mbed-os. If the value is `False`, fetch mbed-os from the remote.
-    """
-    program = MbedProgram.from_new(path)
-    if not create_only:
-        libs = LibraryReferences(root=program.root, ignore_paths=["mbed-os"])
-        libs.fetch()
-
-
-def deploy_project(path: pathlib.Path, force: bool = False) -> None:
-    """Deploy a specific revision of the current Mbed project.
-
-    This function also resolves and syncs all library dependencies to the revision specified in the library reference
-    files.
-
-    Args:
-        path: Path to the Mbed project.
-        force: Force overwrite uncommitted changes. If False, the deploy will fail if there are uncommitted local
-               changes.
-    """
-    libs = LibraryReferences(path, ignore_paths=["mbed-os"])
-    libs.checkout(force=force)
-    if list(libs.iter_unresolved()):
-        logger.info("Unresolved libraries detected, downloading library source code.")
-        libs.fetch()
-
-
-def get_known_libs(path: pathlib.Path) -> List:
-    """List all resolved library dependencies.
-
-    This function will not resolve dependencies. This will only generate a list of resolved dependencies.
-
-    Args:
-        path: Path to the Mbed project.
-
-    Returns:
-        A list of known dependencies.
-    """
-    libs = LibraryReferences(path, ignore_paths=["mbed-os"])
-    return list(sorted(libs.iter_resolved()))
-
-
-
-
-
-
-
-

Functions

-
-
-def deploy_project(path: pathlib.Path, force: bool = False) ‑> None -
-
-

Deploy a specific revision of the current Mbed project.

-

This function also resolves and syncs all library dependencies to the revision specified in the library reference -files.

-

Args

-
-
path
-
Path to the Mbed project.
-
force
-
Force overwrite uncommitted changes. If False, the deploy will fail if there are uncommitted local -changes.
-
-
- -Expand source code - -
def deploy_project(path: pathlib.Path, force: bool = False) -> None:
-    """Deploy a specific revision of the current Mbed project.
-
-    This function also resolves and syncs all library dependencies to the revision specified in the library reference
-    files.
-
-    Args:
-        path: Path to the Mbed project.
-        force: Force overwrite uncommitted changes. If False, the deploy will fail if there are uncommitted local
-               changes.
-    """
-    libs = LibraryReferences(path, ignore_paths=["mbed-os"])
-    libs.checkout(force=force)
-    if list(libs.iter_unresolved()):
-        logger.info("Unresolved libraries detected, downloading library source code.")
-        libs.fetch()
-
-
-
-def get_known_libs(path: pathlib.Path) ‑> List[~T] -
-
-

List all resolved library dependencies.

-

This function will not resolve dependencies. This will only generate a list of resolved dependencies.

-

Args

-
-
path
-
Path to the Mbed project.
-
-

Returns

-

A list of known dependencies.

-
- -Expand source code - -
def get_known_libs(path: pathlib.Path) -> List:
-    """List all resolved library dependencies.
-
-    This function will not resolve dependencies. This will only generate a list of resolved dependencies.
-
-    Args:
-        path: Path to the Mbed project.
-
-    Returns:
-        A list of known dependencies.
-    """
-    libs = LibraryReferences(path, ignore_paths=["mbed-os"])
-    return list(sorted(libs.iter_resolved()))
-
-
-
-def import_project(url: str, dst_path: Any = None, recursive: bool = False) ‑> pathlib.Path -
-
-

Clones an Mbed project from a remote repository.

-

Args

-
-
url
-
URL of the repository to clone.
-
dst_path
-
Destination path for the repository.
-
recursive
-
Recursively clone all project dependencies.
-
-

Returns

-

The path the project was cloned to.

-
- -Expand source code - -
def import_project(url: str, dst_path: Any = None, recursive: bool = False) -> pathlib.Path:
-    """Clones an Mbed project from a remote repository.
-
-    Args:
-        url: URL of the repository to clone.
-        dst_path: Destination path for the repository.
-        recursive: Recursively clone all project dependencies.
-
-    Returns:
-        The path the project was cloned to.
-    """
-    git_data = parse_url(url)
-    url = git_data["url"]
-    if not dst_path:
-        dst_path = pathlib.Path(git_data["dst_path"])
-
-    git_utils.clone(url, dst_path)
-    if recursive:
-        libs = LibraryReferences(root=dst_path, ignore_paths=["mbed-os"])
-        libs.fetch()
-
-    return dst_path
-
-
-
-def initialise_project(path: pathlib.Path, create_only: bool) ‑> None -
-
-

Create a new Mbed project, optionally fetching and adding mbed-os.

-

Args

-
-
path
-
Path to the project folder. Created if it doesn't exist.
-
create_only
-
Flag which suppreses fetching mbed-os. If the value is False, fetch mbed-os from the remote.
-
-
- -Expand source code - -
def initialise_project(path: pathlib.Path, create_only: bool) -> None:
-    """Create a new Mbed project, optionally fetching and adding mbed-os.
-
-    Args:
-        path: Path to the project folder. Created if it doesn't exist.
-        create_only: Flag which suppreses fetching mbed-os. If the value is `False`, fetch mbed-os from the remote.
-    """
-    program = MbedProgram.from_new(path)
-    if not create_only:
-        libs = LibraryReferences(root=program.root, ignore_paths=["mbed-os"])
-        libs.fetch()
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/sterm/index.html b/docs/api/sterm/index.html deleted file mode 100644 index ba574bba..00000000 --- a/docs/api/sterm/index.html +++ /dev/null @@ -1,76 +0,0 @@ - - - - - - -mbed_tools.sterm API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.sterm

-
-
-

Package containing sterm functionality.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Package containing sterm functionality."""
-
-
-
-

Sub-modules

-
-
mbed_tools.sterm.terminal
-
-

Serial terminal implementation based on pyserial.tools.miniterm …

-
-
-
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/sterm/terminal.html b/docs/api/sterm/terminal.html deleted file mode 100644 index c3c13d89..00000000 --- a/docs/api/sterm/terminal.html +++ /dev/null @@ -1,419 +0,0 @@ - - - - - - -mbed_tools.sterm.terminal API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.sterm.terminal

-
-
-

Serial terminal implementation based on pyserial.tools.miniterm.

-

The Mbed serial terminal makes the following modifications to the default Miniterm. -* Custom help menu text -* Constrained set of menu keys -* CTRL-H to show help -* CTRL-B sends serial break to the target

-

To start the terminal clients should call the "run" function, this is the entry point to the module.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Serial terminal implementation based on pyserial.tools.miniterm.
-
-The Mbed serial terminal makes the following modifications to the default Miniterm.
-* Custom help menu text
-* Constrained set of menu keys
-* CTRL-H to show help
-* CTRL-B sends serial break to the target
-
-To start the terminal clients should call the "run" function, this is the entry point to the module.
-"""
-from typing import Any
-
-from serial import Serial
-from serial.tools.miniterm import Miniterm
-
-
-def run(port: str, baud: int, echo: bool = True) -> None:
-    """Run the serial terminal.
-
-    This function is blocking as it waits for the terminal thread to finish executing before returning.
-
-    Args:
-        port: The serial port to open a terminal on.
-        baud: Serial baud rate.
-        echo: Echo user input back to the console.
-    """
-    term = SerialTerminal(Serial(port=port, baudrate=str(baud)), echo=echo)
-    term.start()
-
-    try:
-        term.join(True)
-    except KeyboardInterrupt:
-        pass
-    finally:
-        term.join()
-        term.close()
-
-
-class SerialTerminal(Miniterm):
-    """An implementation of Miniterm that implements the additional Mbed terminal functionality.
-
-    Overrides the `writer` method to implement modified menu key handling behaviour.
-    Overrides the Miniterm::get_help_text method to return the Mbed custom help text.
-    Adds a `reset` method so users can send a reset signal to the device.
-    """
-
-    def __init__(self, *args: Any, **kwargs: Any) -> None:
-        """Set the rx/tx encoding and special characters."""
-        super().__init__(*args, **kwargs)
-        self.exit_character = CTRL_C
-        self.menu_character = CTRL_T
-        self.reset_character = CTRL_B
-        self.help_character = CTRL_H
-        self.set_rx_encoding("UTF-8")
-        self.set_tx_encoding("UTF-8")
-
-    def reset(self) -> None:
-        """Send a reset signal."""
-        self.serial.sendBreak()
-
-    def get_help_text(self) -> str:
-        """Return the text displayed when the user requests help."""
-        return HELP_TEXT
-
-    def writer(self) -> None:
-        """Implements terminal behaviour."""
-        menu_active = False
-        while self.alive:
-            try:
-                input_key = self.console.getkey()
-            except KeyboardInterrupt:
-                input_key = self.exit_character
-
-            if (menu_active and input_key in VALID_MENU_KEYS) or (input_key == self.help_character):
-                self.handle_menu_key(input_key)
-                menu_active = False
-
-            elif input_key == self.menu_character:
-                menu_active = True
-
-            elif input_key == self.reset_character:
-                self.reset()
-
-            elif input_key == self.exit_character:
-                self.stop()
-                break
-
-            else:
-                self._write_transformed_char(input_key)
-
-                if self.echo:
-                    self._echo_transformed_char(input_key)
-
-    def _write_transformed_char(self, text: str) -> None:
-        for transformation in self.tx_transformations:
-            text = transformation.tx(text)
-
-        self.serial.write(self.tx_encoder.encode(text))
-
-    def _echo_transformed_char(self, text: str) -> None:
-        for transformation in self.tx_transformations:
-            text = transformation.echo(text)
-
-        self.console.write(text)
-
-
-CTRL_B = "\x02"
-CTRL_C = "\x03"
-CTRL_H = "\x08"
-CTRL_T = "\x14"
-VALID_MENU_KEYS = ("p", "b", "\t", "\x01", "\x04", "\x05", "\x06", "\x0c", CTRL_C, CTRL_T)
-HELP_TEXT = """--- Mbed Serial Terminal
---- Based on miniterm from pySerial
----
---- Ctrl+b     Send Break (reset target)
---- Ctrl+c     Exit terminal
---- Ctrl+h     Help
---- Ctrl+t     Menu escape key, followed by:
----    p       Change COM port
----    b       Change baudrate
----    Tab     Show detailed terminal info
----    Ctrl+a  Change encoding (default UTF-8)
----    Ctrl+f  Edit filters
----    Ctrl+e  Toggle local echo
----    Ctrl+l  Toggle EOL
----    Ctrl+r  Toggle RTS
----    Ctrl+d  Toggle DTR
----    Ctrl+c  Send control character to remote
----    Ctrl+t  Send control character to remote
-"""
-
-
-
-
-
-
-
-

Functions

-
-
-def run(port: str, baud: int, echo: bool = True) ‑> None -
-
-

Run the serial terminal.

-

This function is blocking as it waits for the terminal thread to finish executing before returning.

-

Args

-
-
port
-
The serial port to open a terminal on.
-
baud
-
Serial baud rate.
-
echo
-
Echo user input back to the console.
-
-
- -Expand source code - -
def run(port: str, baud: int, echo: bool = True) -> None:
-    """Run the serial terminal.
-
-    This function is blocking as it waits for the terminal thread to finish executing before returning.
-
-    Args:
-        port: The serial port to open a terminal on.
-        baud: Serial baud rate.
-        echo: Echo user input back to the console.
-    """
-    term = SerialTerminal(Serial(port=port, baudrate=str(baud)), echo=echo)
-    term.start()
-
-    try:
-        term.join(True)
-    except KeyboardInterrupt:
-        pass
-    finally:
-        term.join()
-        term.close()
-
-
-
-
-
-

Classes

-
-
-class SerialTerminal -(*args: Any, **kwargs: Any) -
-
-

An implementation of Miniterm that implements the additional Mbed terminal functionality.

-

Overrides the writer method to implement modified menu key handling behaviour. -Overrides the Miniterm::get_help_text method to return the Mbed custom help text. -Adds a reset method so users can send a reset signal to the device.

-

Set the rx/tx encoding and special characters.

-
- -Expand source code - -
class SerialTerminal(Miniterm):
-    """An implementation of Miniterm that implements the additional Mbed terminal functionality.
-
-    Overrides the `writer` method to implement modified menu key handling behaviour.
-    Overrides the Miniterm::get_help_text method to return the Mbed custom help text.
-    Adds a `reset` method so users can send a reset signal to the device.
-    """
-
-    def __init__(self, *args: Any, **kwargs: Any) -> None:
-        """Set the rx/tx encoding and special characters."""
-        super().__init__(*args, **kwargs)
-        self.exit_character = CTRL_C
-        self.menu_character = CTRL_T
-        self.reset_character = CTRL_B
-        self.help_character = CTRL_H
-        self.set_rx_encoding("UTF-8")
-        self.set_tx_encoding("UTF-8")
-
-    def reset(self) -> None:
-        """Send a reset signal."""
-        self.serial.sendBreak()
-
-    def get_help_text(self) -> str:
-        """Return the text displayed when the user requests help."""
-        return HELP_TEXT
-
-    def writer(self) -> None:
-        """Implements terminal behaviour."""
-        menu_active = False
-        while self.alive:
-            try:
-                input_key = self.console.getkey()
-            except KeyboardInterrupt:
-                input_key = self.exit_character
-
-            if (menu_active and input_key in VALID_MENU_KEYS) or (input_key == self.help_character):
-                self.handle_menu_key(input_key)
-                menu_active = False
-
-            elif input_key == self.menu_character:
-                menu_active = True
-
-            elif input_key == self.reset_character:
-                self.reset()
-
-            elif input_key == self.exit_character:
-                self.stop()
-                break
-
-            else:
-                self._write_transformed_char(input_key)
-
-                if self.echo:
-                    self._echo_transformed_char(input_key)
-
-    def _write_transformed_char(self, text: str) -> None:
-        for transformation in self.tx_transformations:
-            text = transformation.tx(text)
-
-        self.serial.write(self.tx_encoder.encode(text))
-
-    def _echo_transformed_char(self, text: str) -> None:
-        for transformation in self.tx_transformations:
-            text = transformation.echo(text)
-
-        self.console.write(text)
-
-

Ancestors

-
    -
  • serial.tools.miniterm.Miniterm
    • -
-

Methods

-
-
-def get_help_text(self) ‑> str -
-
-

Return the text displayed when the user requests help.

-
- -Expand source code - -
def get_help_text(self) -> str:
-    """Return the text displayed when the user requests help."""
-    return HELP_TEXT
-
-
-
-def reset(self) ‑> None -
-
-

Send a reset signal.

-
- -Expand source code - -
def reset(self) -> None:
-    """Send a reset signal."""
-    self.serial.sendBreak()
-
-
-
-def writer(self) ‑> None -
-
-

Implements terminal behaviour.

-
- -Expand source code - -
def writer(self) -> None:
-    """Implements terminal behaviour."""
-    menu_active = False
-    while self.alive:
-        try:
-            input_key = self.console.getkey()
-        except KeyboardInterrupt:
-            input_key = self.exit_character
-
-        if (menu_active and input_key in VALID_MENU_KEYS) or (input_key == self.help_character):
-            self.handle_menu_key(input_key)
-            menu_active = False
-
-        elif input_key == self.menu_character:
-            menu_active = True
-
-        elif input_key == self.reset_character:
-            self.reset()
-
-        elif input_key == self.exit_character:
-            self.stop()
-            break
-
-        else:
-            self._write_transformed_char(input_key)
-
-            if self.echo:
-                self._echo_transformed_char(input_key)
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/targets/board.html b/docs/api/targets/board.html deleted file mode 100644 index d234d0fc..00000000 --- a/docs/api/targets/board.html +++ /dev/null @@ -1,364 +0,0 @@ - - - - - - -mbed_tools.targets.board API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.targets.board

-
-
-

Representation of an Mbed-Enabled Development Board and related utilities.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Representation of an Mbed-Enabled Development Board and related utilities."""
-from dataclasses import dataclass
-from typing import Tuple
-
-
-@dataclass(frozen=True, order=True)
-class Board:
-    """Representation of an Mbed-Enabled Development Board.
-
-    Attributes:
-        board_type: Type of board in format that allows cross-referencing with target definitions.
-        board_name: Human readable name.
-        product_code: Uniquely identifies a board for the online compiler.
-        target_type: A confusing term that is not related to 'target' in other parts of the code.
-        Identifies if a board in the online database is a `module` or a `platform` (modules are more
-        complex and often have supplementary sensors, displays etc. A platform is a normal development board).
-        slug: Used with target_type to identify a board's page on the mbed website.
-        build_variant: Available build variants for the board.
-        Can be used in conjunction with board_type for referencing targets.
-        mbed_os_support: The versions of Mbed OS supported.
-        mbed_enabled: Whether Mbed OS is supported or not.
-    """
-
-    board_type: str
-    board_name: str
-    product_code: str
-    target_type: str
-    slug: str
-    build_variant: Tuple[str, ...]
-    mbed_os_support: Tuple[str, ...]
-    mbed_enabled: Tuple[str, ...]
-
-    @classmethod
-    def from_online_board_entry(cls, board_entry: dict) -> "Board":
-        """Create a new instance of Board from an online database entry.
-
-        Args:
-            board_entry: A single entity retrieved from the board database API.
-        """
-        board_attrs = board_entry.get("attributes", {})
-        board_features = board_attrs.get("features", {})
-
-        return cls(
-            # Online database has inconsistently cased board types.
-            # Since this field is used to match against `targets.json`, we need to ensure consistency is maintained.
-            board_type=board_attrs.get("board_type", "").upper(),
-            board_name=board_attrs.get("name", ""),
-            mbed_os_support=tuple(board_features.get("mbed_os_support", [])),
-            mbed_enabled=tuple(board_features.get("mbed_enabled", [])),
-            product_code=board_attrs.get("product_code", ""),
-            target_type=board_attrs.get("target_type", ""),
-            slug=board_attrs.get("slug", ""),
-            # TODO: Remove this hard-coded example after demoing.
-            # NOTE: Currently we hard-code the build variant for a single board type.
-            # This is simply so we can demo the tools to PE. This must be removed and replaced with a proper mechanism
-            # for determining the build variant for all platforms. We probably need to add this information to the
-            # boards database.
-            build_variant=tuple(),
-        )
-
-    @classmethod
-    def from_offline_board_entry(cls, board_entry: dict) -> "Board":
-        """Construct an Board with data from the offline database snapshot."""
-        return cls(
-            board_type=board_entry.get("board_type", ""),
-            board_name=board_entry.get("board_name", ""),
-            product_code=board_entry.get("product_code", ""),
-            target_type=board_entry.get("target_type", ""),
-            slug=board_entry.get("slug", ""),
-            mbed_os_support=tuple(board_entry.get("mbed_os_support", [])),
-            mbed_enabled=tuple(board_entry.get("mbed_enabled", [])),
-            build_variant=tuple(board_entry.get("build_variant", [])),
-        )
-
-
-
-
-
-
-
-
-
-

Classes

-
-
-class Board -(board_type: str, board_name: str, product_code: str, target_type: str, slug: str, build_variant: Tuple[str, ...], mbed_os_support: Tuple[str, ...], mbed_enabled: Tuple[str, ...]) -
-
-

Representation of an Mbed-Enabled Development Board.

-

Attributes

-
-
board_type
-
Type of board in format that allows cross-referencing with target definitions.
-
board_name
-
Human readable name.
-
product_code
-
Uniquely identifies a board for the online compiler.
-
target_type
-
A confusing term that is not related to 'target' in other parts of the code.
-
Identifies if a board in the online database is a module or a platform (modules are more
-
complex and often have supplementary sensors, displays etc. A platform is a normal development board).
-
slug
-
Used with target_type to identify a board's page on the mbed website.
-
build_variant
-
Available build variants for the board.
-
Can be used in conjunction with board_type for referencing targets.
-
mbed_os_support
-
The versions of Mbed OS supported.
-
mbed_enabled
-
Whether Mbed OS is supported or not.
-
-
- -Expand source code - -
class Board:
-    """Representation of an Mbed-Enabled Development Board.
-
-    Attributes:
-        board_type: Type of board in format that allows cross-referencing with target definitions.
-        board_name: Human readable name.
-        product_code: Uniquely identifies a board for the online compiler.
-        target_type: A confusing term that is not related to 'target' in other parts of the code.
-        Identifies if a board in the online database is a `module` or a `platform` (modules are more
-        complex and often have supplementary sensors, displays etc. A platform is a normal development board).
-        slug: Used with target_type to identify a board's page on the mbed website.
-        build_variant: Available build variants for the board.
-        Can be used in conjunction with board_type for referencing targets.
-        mbed_os_support: The versions of Mbed OS supported.
-        mbed_enabled: Whether Mbed OS is supported or not.
-    """
-
-    board_type: str
-    board_name: str
-    product_code: str
-    target_type: str
-    slug: str
-    build_variant: Tuple[str, ...]
-    mbed_os_support: Tuple[str, ...]
-    mbed_enabled: Tuple[str, ...]
-
-    @classmethod
-    def from_online_board_entry(cls, board_entry: dict) -> "Board":
-        """Create a new instance of Board from an online database entry.
-
-        Args:
-            board_entry: A single entity retrieved from the board database API.
-        """
-        board_attrs = board_entry.get("attributes", {})
-        board_features = board_attrs.get("features", {})
-
-        return cls(
-            # Online database has inconsistently cased board types.
-            # Since this field is used to match against `targets.json`, we need to ensure consistency is maintained.
-            board_type=board_attrs.get("board_type", "").upper(),
-            board_name=board_attrs.get("name", ""),
-            mbed_os_support=tuple(board_features.get("mbed_os_support", [])),
-            mbed_enabled=tuple(board_features.get("mbed_enabled", [])),
-            product_code=board_attrs.get("product_code", ""),
-            target_type=board_attrs.get("target_type", ""),
-            slug=board_attrs.get("slug", ""),
-            # TODO: Remove this hard-coded example after demoing.
-            # NOTE: Currently we hard-code the build variant for a single board type.
-            # This is simply so we can demo the tools to PE. This must be removed and replaced with a proper mechanism
-            # for determining the build variant for all platforms. We probably need to add this information to the
-            # boards database.
-            build_variant=tuple(),
-        )
-
-    @classmethod
-    def from_offline_board_entry(cls, board_entry: dict) -> "Board":
-        """Construct an Board with data from the offline database snapshot."""
-        return cls(
-            board_type=board_entry.get("board_type", ""),
-            board_name=board_entry.get("board_name", ""),
-            product_code=board_entry.get("product_code", ""),
-            target_type=board_entry.get("target_type", ""),
-            slug=board_entry.get("slug", ""),
-            mbed_os_support=tuple(board_entry.get("mbed_os_support", [])),
-            mbed_enabled=tuple(board_entry.get("mbed_enabled", [])),
-            build_variant=tuple(board_entry.get("build_variant", [])),
-        )
-
-

Class variables

-
-
var board_name : str
-
-
-
-
var board_type : str
-
-
-
-
var build_variant : Tuple[str, ...]
-
-
-
-
var mbed_enabled : Tuple[str, ...]
-
-
-
-
var mbed_os_support : Tuple[str, ...]
-
-
-
-
var product_code : str
-
-
-
-
var slug : str
-
-
-
-
var target_type : str
-
-
-
-
-

Static methods

-
-
-def from_offline_board_entry(board_entry: dict) ‑> Board -
-
-

Construct an Board with data from the offline database snapshot.

-
- -Expand source code - -
@classmethod
-def from_offline_board_entry(cls, board_entry: dict) -> "Board":
-    """Construct an Board with data from the offline database snapshot."""
-    return cls(
-        board_type=board_entry.get("board_type", ""),
-        board_name=board_entry.get("board_name", ""),
-        product_code=board_entry.get("product_code", ""),
-        target_type=board_entry.get("target_type", ""),
-        slug=board_entry.get("slug", ""),
-        mbed_os_support=tuple(board_entry.get("mbed_os_support", [])),
-        mbed_enabled=tuple(board_entry.get("mbed_enabled", [])),
-        build_variant=tuple(board_entry.get("build_variant", [])),
-    )
-
-
-
-def from_online_board_entry(board_entry: dict) ‑> Board -
-
-

Create a new instance of Board from an online database entry.

-

Args

-
-
board_entry
-
A single entity retrieved from the board database API.
-
-
- -Expand source code - -
@classmethod
-def from_online_board_entry(cls, board_entry: dict) -> "Board":
-    """Create a new instance of Board from an online database entry.
-
-    Args:
-        board_entry: A single entity retrieved from the board database API.
-    """
-    board_attrs = board_entry.get("attributes", {})
-    board_features = board_attrs.get("features", {})
-
-    return cls(
-        # Online database has inconsistently cased board types.
-        # Since this field is used to match against `targets.json`, we need to ensure consistency is maintained.
-        board_type=board_attrs.get("board_type", "").upper(),
-        board_name=board_attrs.get("name", ""),
-        mbed_os_support=tuple(board_features.get("mbed_os_support", [])),
-        mbed_enabled=tuple(board_features.get("mbed_enabled", [])),
-        product_code=board_attrs.get("product_code", ""),
-        target_type=board_attrs.get("target_type", ""),
-        slug=board_attrs.get("slug", ""),
-        # TODO: Remove this hard-coded example after demoing.
-        # NOTE: Currently we hard-code the build variant for a single board type.
-        # This is simply so we can demo the tools to PE. This must be removed and replaced with a proper mechanism
-        # for determining the build variant for all platforms. We probably need to add this information to the
-        # boards database.
-        build_variant=tuple(),
-    )
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/targets/boards.html b/docs/api/targets/boards.html deleted file mode 100644 index ba055745..00000000 --- a/docs/api/targets/boards.html +++ /dev/null @@ -1,362 +0,0 @@ - - - - - - -mbed_tools.targets.boards API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.targets.boards

-
-
-

Interface to the Board Database.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Interface to the Board Database."""
-import json
-
-from dataclasses import asdict
-from collections.abc import Set
-from typing import Iterator, Iterable, Any, Callable
-
-from mbed_tools.targets._internal import board_database
-
-from mbed_tools.targets.exceptions import UnknownBoard
-from mbed_tools.targets.board import Board
-
-
-class Boards(Set):
-    """Interface to the Board Database.
-
-    Boards is initialised with an Iterable[Board]. The classmethods
-    can be used to construct Boards with data from either the online or offline database.
-    """
-
-    @classmethod
-    def from_offline_database(cls) -> "Boards":
-        """Initialise with the offline board database.
-
-        Raises:
-            BoardDatabaseError: Could not retrieve data from the board database.
-        """
-        return cls(Board.from_offline_board_entry(b) for b in board_database.get_offline_board_data())
-
-    @classmethod
-    def from_online_database(cls) -> "Boards":
-        """Initialise with the online board database.
-
-        Raises:
-            BoardDatabaseError: Could not retrieve data from the board database.
-        """
-        return cls(Board.from_online_board_entry(b) for b in board_database.get_online_board_data())
-
-    def __init__(self, boards_data: Iterable["Board"]) -> None:
-        """Initialise with a list of boards.
-
-        Args:
-            boards_data: iterable of board data from a board database source.
-        """
-        self._boards_data = tuple(boards_data)
-
-    def __iter__(self) -> Iterator["Board"]:
-        """Yield an Board on each iteration."""
-        for board in self._boards_data:
-            yield board
-
-    def __len__(self) -> int:
-        """Return the number of boards."""
-        return len(self._boards_data)
-
-    def __contains__(self, board: object) -> Any:
-        """Check if a board is in the collection of boards.
-
-        Args:
-            board: An instance of Board.
-        """
-        if not isinstance(board, Board):
-            return False
-
-        return any(x == board for x in self)
-
-    def get_board(self, matching: Callable) -> Board:
-        """Returns first Board for which `matching` returns True.
-
-        Args:
-            matching: A function which will be called for each board in database
-
-        Raises:
-            UnknownBoard: the given product code was not found in the board database.
-        """
-        try:
-            return next(board for board in self if matching(board))
-        except StopIteration:
-            raise UnknownBoard()
-
-    def json_dump(self) -> str:
-        """Return the contents of the board database as a json string."""
-        return json.dumps([asdict(b) for b in self], indent=4)
-
-
-
-
-
-
-
-
-
-

Classes

-
-
-class Boards -(boards_data: Iterable[ForwardRef('Board')]) -
-
-

Interface to the Board Database.

-

Boards is initialised with an Iterable[Board]. The classmethods -can be used to construct Boards with data from either the online or offline database.

-

Initialise with a list of boards.

-

Args

-
-
boards_data
-
iterable of board data from a board database source.
-
-
- -Expand source code - -
class Boards(Set):
-    """Interface to the Board Database.
-
-    Boards is initialised with an Iterable[Board]. The classmethods
-    can be used to construct Boards with data from either the online or offline database.
-    """
-
-    @classmethod
-    def from_offline_database(cls) -> "Boards":
-        """Initialise with the offline board database.
-
-        Raises:
-            BoardDatabaseError: Could not retrieve data from the board database.
-        """
-        return cls(Board.from_offline_board_entry(b) for b in board_database.get_offline_board_data())
-
-    @classmethod
-    def from_online_database(cls) -> "Boards":
-        """Initialise with the online board database.
-
-        Raises:
-            BoardDatabaseError: Could not retrieve data from the board database.
-        """
-        return cls(Board.from_online_board_entry(b) for b in board_database.get_online_board_data())
-
-    def __init__(self, boards_data: Iterable["Board"]) -> None:
-        """Initialise with a list of boards.
-
-        Args:
-            boards_data: iterable of board data from a board database source.
-        """
-        self._boards_data = tuple(boards_data)
-
-    def __iter__(self) -> Iterator["Board"]:
-        """Yield an Board on each iteration."""
-        for board in self._boards_data:
-            yield board
-
-    def __len__(self) -> int:
-        """Return the number of boards."""
-        return len(self._boards_data)
-
-    def __contains__(self, board: object) -> Any:
-        """Check if a board is in the collection of boards.
-
-        Args:
-            board: An instance of Board.
-        """
-        if not isinstance(board, Board):
-            return False
-
-        return any(x == board for x in self)
-
-    def get_board(self, matching: Callable) -> Board:
-        """Returns first Board for which `matching` returns True.
-
-        Args:
-            matching: A function which will be called for each board in database
-
-        Raises:
-            UnknownBoard: the given product code was not found in the board database.
-        """
-        try:
-            return next(board for board in self if matching(board))
-        except StopIteration:
-            raise UnknownBoard()
-
-    def json_dump(self) -> str:
-        """Return the contents of the board database as a json string."""
-        return json.dumps([asdict(b) for b in self], indent=4)
-
-

Ancestors

-
    -
  • collections.abc.Set
    • -
  • collections.abc.Collection
    • -
  • collections.abc.Sized
    • -
  • collections.abc.Iterable
    • -
  • collections.abc.Container
    • -
-

Static methods

-
-
-def from_offline_database() ‑> Boards -
-
-

Initialise with the offline board database.

-

Raises

-
-
BoardDatabaseError
-
Could not retrieve data from the board database.
-
-
- -Expand source code - -
@classmethod
-def from_offline_database(cls) -> "Boards":
-    """Initialise with the offline board database.
-
-    Raises:
-        BoardDatabaseError: Could not retrieve data from the board database.
-    """
-    return cls(Board.from_offline_board_entry(b) for b in board_database.get_offline_board_data())
-
-
-
-def from_online_database() ‑> Boards -
-
-

Initialise with the online board database.

-

Raises

-
-
BoardDatabaseError
-
Could not retrieve data from the board database.
-
-
- -Expand source code - -
@classmethod
-def from_online_database(cls) -> "Boards":
-    """Initialise with the online board database.
-
-    Raises:
-        BoardDatabaseError: Could not retrieve data from the board database.
-    """
-    return cls(Board.from_online_board_entry(b) for b in board_database.get_online_board_data())
-
-
-
-

Methods

-
-
-def get_board(self, matching: Callable) ‑> Board -
-
-

Returns first Board for which matching returns True.

-

Args

-
-
matching
-
A function which will be called for each board in database
-
-

Raises

-
-
UnknownBoard
-
the given product code was not found in the board database.
-
-
- -Expand source code - -
def get_board(self, matching: Callable) -> Board:
-    """Returns first Board for which `matching` returns True.
-
-    Args:
-        matching: A function which will be called for each board in database
-
-    Raises:
-        UnknownBoard: the given product code was not found in the board database.
-    """
-    try:
-        return next(board for board in self if matching(board))
-    except StopIteration:
-        raise UnknownBoard()
-
-
-
-def json_dump(self) ‑> str -
-
-

Return the contents of the board database as a json string.

-
- -Expand source code - -
def json_dump(self) -> str:
-    """Return the contents of the board database as a json string."""
-    return json.dumps([asdict(b) for b in self], indent=4)
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/targets/env.html b/docs/api/targets/env.html deleted file mode 100644 index d610922c..00000000 --- a/docs/api/targets/env.html +++ /dev/null @@ -1,300 +0,0 @@ - - - - - - -mbed_tools.targets.env API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.targets.env

-
-
-

Environment options for mbed-targets.

-

All the env configuration options can be set either via environment variables or using a .env file -containing the variable definitions as follows:

-
VARIABLE=value
-
-

Environment variables take precendence, meaning the values set in the file will be overriden -by any values previously set in your environment.

-
-

Warning

-

Do not upload .env files containing private tokens to version control! If you use this package -as a dependency of your project, please ensure to include the .env in your .gitignore.

-
-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Environment options for `mbed-targets`.
-
-All the env configuration options can be set either via environment variables or using a `.env` file
-containing the variable definitions as follows:
-
-```
-VARIABLE=value
-```
-
-Environment variables take precendence, meaning the values set in the file will be overriden
-by any values previously set in your environment.
-
-.. WARNING::
-   Do not upload `.env` files containing private tokens to version control! If you use this package
-   as a dependency of your project, please ensure to include the `.env` in your `.gitignore`.
-"""
-import os
-
-import dotenv
-import pdoc
-
-dotenv.load_dotenv(dotenv.find_dotenv(usecwd=True))
-
-
-class Env:
-    """Provides access to environment variables.
-
-    Ensures variables are reloaded when environment changes during runtime.
-    Additionally allows to expose documented instance variables in pdoc
-    generated output.
-    """
-
-    @property
-    def MBED_API_AUTH_TOKEN(self) -> str:
-        """Token to use when accessing online API.
-
-        Mbed Targets uses the online mbed board database at os.mbed.com as its data source.
-        A snapshot of the board database is shipped with the package, for faster lookup of known
-        boards. Only public boards are stored in the database snapshot. If you are fetching data
-        for a private board, mbed-targets will need to contact the online database.
-
-        To fetch data about private boards from the online database, the user must have an account
-        on os.mbed.com and be member of a vendor team that has permissions to see the private board.
-        An authentication token for the team member must be provided in an environment variable named
-        `MBED_API_AUTH_TOKEN`.
-        """
-        return os.getenv("MBED_API_AUTH_TOKEN", "")
-
-    @property
-    def MBED_DATABASE_MODE(self) -> str:
-        """Database mode to use when retrieving board data.
-
-        Mbed Targets supports an online and offline mode, which controls where to look up the board database.
-
-        The board lookup can be from either the online or offline database, depending
-        on the value of an environment variable called `MBED_DATABASE_MODE`.
-
-        The mode can be set to one of the following:
-
-        - `AUTO`: the offline database is searched first, if the board isn't found the online database is searched.
-        - `ONLINE`: the online database is always used.
-        - `OFFLINE`: the offline database is always used.
-
-        If `MBED_DATABASE_MODE` is not set, it defaults to `AUTO`.
-        """
-        return os.getenv("MBED_DATABASE_MODE", "AUTO")
-
-
-env = Env()
-"""Instance of `Env` class."""
-
-env_variables = pdoc.Class("Env", pdoc.Module("mbed_tools.targets.env"), Env).instance_variables()
-
-
-
-
-
-

Global variables

-
-
var env
-
-

Instance of Env class.

-
-
-
-
-
-
-

Classes

-
-
-class Env -
-
-

Provides access to environment variables.

-

Ensures variables are reloaded when environment changes during runtime. -Additionally allows to expose documented instance variables in pdoc -generated output.

-
- -Expand source code - -
class Env:
-    """Provides access to environment variables.
-
-    Ensures variables are reloaded when environment changes during runtime.
-    Additionally allows to expose documented instance variables in pdoc
-    generated output.
-    """
-
-    @property
-    def MBED_API_AUTH_TOKEN(self) -> str:
-        """Token to use when accessing online API.
-
-        Mbed Targets uses the online mbed board database at os.mbed.com as its data source.
-        A snapshot of the board database is shipped with the package, for faster lookup of known
-        boards. Only public boards are stored in the database snapshot. If you are fetching data
-        for a private board, mbed-targets will need to contact the online database.
-
-        To fetch data about private boards from the online database, the user must have an account
-        on os.mbed.com and be member of a vendor team that has permissions to see the private board.
-        An authentication token for the team member must be provided in an environment variable named
-        `MBED_API_AUTH_TOKEN`.
-        """
-        return os.getenv("MBED_API_AUTH_TOKEN", "")
-
-    @property
-    def MBED_DATABASE_MODE(self) -> str:
-        """Database mode to use when retrieving board data.
-
-        Mbed Targets supports an online and offline mode, which controls where to look up the board database.
-
-        The board lookup can be from either the online or offline database, depending
-        on the value of an environment variable called `MBED_DATABASE_MODE`.
-
-        The mode can be set to one of the following:
-
-        - `AUTO`: the offline database is searched first, if the board isn't found the online database is searched.
-        - `ONLINE`: the online database is always used.
-        - `OFFLINE`: the offline database is always used.
-
-        If `MBED_DATABASE_MODE` is not set, it defaults to `AUTO`.
-        """
-        return os.getenv("MBED_DATABASE_MODE", "AUTO")
-
-

Instance variables

-
-
var MBED_API_AUTH_TOKEN : str
-
-

Token to use when accessing online API.

-

Mbed Targets uses the online mbed board database at os.mbed.com as its data source. -A snapshot of the board database is shipped with the package, for faster lookup of known -boards. Only public boards are stored in the database snapshot. If you are fetching data -for a private board, mbed-targets will need to contact the online database.

-

To fetch data about private boards from the online database, the user must have an account -on os.mbed.com and be member of a vendor team that has permissions to see the private board. -An authentication token for the team member must be provided in an environment variable named -MBED_API_AUTH_TOKEN.

-
- -Expand source code - -
@property
-def MBED_API_AUTH_TOKEN(self) -> str:
-    """Token to use when accessing online API.
-
-    Mbed Targets uses the online mbed board database at os.mbed.com as its data source.
-    A snapshot of the board database is shipped with the package, for faster lookup of known
-    boards. Only public boards are stored in the database snapshot. If you are fetching data
-    for a private board, mbed-targets will need to contact the online database.
-
-    To fetch data about private boards from the online database, the user must have an account
-    on os.mbed.com and be member of a vendor team that has permissions to see the private board.
-    An authentication token for the team member must be provided in an environment variable named
-    `MBED_API_AUTH_TOKEN`.
-    """
-    return os.getenv("MBED_API_AUTH_TOKEN", "")
-
-
-
var MBED_DATABASE_MODE : str
-
-

Database mode to use when retrieving board data.

-

Mbed Targets supports an online and offline mode, which controls where to look up the board database.

-

The board lookup can be from either the online or offline database, depending -on the value of an environment variable called MBED_DATABASE_MODE.

-

The mode can be set to one of the following:

-
    -
  • AUTO: the offline database is searched first, if the board isn't found the online database is searched.
    • -
  • ONLINE: the online database is always used.
    • -
  • OFFLINE: the offline database is always used.
    • -
-

If MBED_DATABASE_MODE is not set, it defaults to AUTO.

-
- -Expand source code - -
@property
-def MBED_DATABASE_MODE(self) -> str:
-    """Database mode to use when retrieving board data.
-
-    Mbed Targets supports an online and offline mode, which controls where to look up the board database.
-
-    The board lookup can be from either the online or offline database, depending
-    on the value of an environment variable called `MBED_DATABASE_MODE`.
-
-    The mode can be set to one of the following:
-
-    - `AUTO`: the offline database is searched first, if the board isn't found the online database is searched.
-    - `ONLINE`: the online database is always used.
-    - `OFFLINE`: the offline database is always used.
-
-    If `MBED_DATABASE_MODE` is not set, it defaults to `AUTO`.
-    """
-    return os.getenv("MBED_DATABASE_MODE", "AUTO")
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/targets/exceptions.html b/docs/api/targets/exceptions.html deleted file mode 100644 index c39d6e2b..00000000 --- a/docs/api/targets/exceptions.html +++ /dev/null @@ -1,223 +0,0 @@ - - - - - - -mbed_tools.targets.exceptions API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.targets.exceptions

-
-
-

Public exceptions exposed by the package.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Public exceptions exposed by the package."""
-
-from mbed_tools.lib.exceptions import ToolsError
-
-
-class MbedTargetsError(ToolsError):
-    """Base exception for mbed-targets."""
-
-
-class TargetError(ToolsError):
-    """Target definition cannot be retrieved."""
-
-
-class UnknownBoard(MbedTargetsError):
-    """Requested board was not found."""
-
-
-class UnsupportedMode(MbedTargetsError):
-    """The Database Mode is unsupported."""
-
-
-class BoardDatabaseError(MbedTargetsError):
-    """Failed to get the board data from the database."""
-
-
-
-
-
-
-
-
-
-

Classes

-
-
-class BoardDatabaseError -(*args, **kwargs) -
-
-

Failed to get the board data from the database.

-
- -Expand source code - -
class BoardDatabaseError(MbedTargetsError):
-    """Failed to get the board data from the database."""
-
-

Ancestors

- -

Subclasses

-
    -
  • mbed_tools.targets._internal.exceptions.BoardAPIError
    • -
  • mbed_tools.targets._internal.exceptions.ResponseJSONError
    • -
-
-
-class MbedTargetsError -(*args, **kwargs) -
-
-

Base exception for mbed-targets.

-
- -Expand source code - -
class MbedTargetsError(ToolsError):
-    """Base exception for mbed-targets."""
-
-

Ancestors

-
    -
  • ToolsError
    • -
  • builtins.Exception
    • -
  • builtins.BaseException
    • -
-

Subclasses

- -
-
-class TargetError -(*args, **kwargs) -
-
-

Target definition cannot be retrieved.

-
- -Expand source code - -
class TargetError(ToolsError):
-    """Target definition cannot be retrieved."""
-
-

Ancestors

-
    -
  • ToolsError
    • -
  • builtins.Exception
    • -
  • builtins.BaseException
    • -
-
-
-class UnknownBoard -(*args, **kwargs) -
-
-

Requested board was not found.

-
- -Expand source code - -
class UnknownBoard(MbedTargetsError):
-    """Requested board was not found."""
-
-

Ancestors

- -
-
-class UnsupportedMode -(*args, **kwargs) -
-
-

The Database Mode is unsupported.

-
- -Expand source code - -
class UnsupportedMode(MbedTargetsError):
-    """The Database Mode is unsupported."""
-
-

Ancestors

- -
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/targets/get_board.html b/docs/api/targets/get_board.html deleted file mode 100644 index 9f5d5041..00000000 --- a/docs/api/targets/get_board.html +++ /dev/null @@ -1,342 +0,0 @@ - - - - - - -mbed_tools.targets.get_board API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.targets.get_board

-
-
-

Interface for accessing Mbed-Enabled Development Board data.

-

An instance of Board can be retrieved by calling one of the public functions.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Interface for accessing Mbed-Enabled Development Board data.
-
-An instance of `mbed_tools.targets.board.Board` can be retrieved by calling one of the public functions.
-"""
-import logging
-from enum import Enum
-from typing import Callable
-
-from mbed_tools.targets.env import env
-from mbed_tools.targets.exceptions import UnknownBoard, UnsupportedMode, BoardDatabaseError
-from mbed_tools.targets.board import Board
-from mbed_tools.targets.boards import Boards
-
-
-logger = logging.getLogger(__name__)
-
-
-def get_board_by_product_code(product_code: str) -> Board:
-    """Returns first `mbed_tools.targets.board.Board` matching given product code.
-
-    Args:
-        product_code: the product code to look up in the database.
-
-    Raises:
-        UnknownBoard: a board with a matching product code was not found.
-    """
-    return get_board(lambda board: board.product_code == product_code)
-
-
-def get_board_by_online_id(slug: str, target_type: str) -> Board:
-    """Returns first `mbed_tools.targets.board.Board` matching given online id.
-
-    Args:
-        slug: The slug to look up in the database.
-        target_type: The target type to look up in the database, normally one of `platform` or `module`.
-
-    Raises:
-        UnknownBoard: a board with a matching slug and target type could not be found.
-    """
-    matched_slug = slug.casefold()
-    return get_board(lambda board: board.slug.casefold() == matched_slug and board.target_type == target_type)
-
-
-def get_board_by_jlink_slug(slug: str) -> Board:
-    """Returns first `mbed-tools.targets.board.Board` matching given slug.
-
-    With J-Link, the slug is extracted from a board manufacturer URL, and may not match
-    the Mbed slug. The J-Link slug is compared against the slug, board_name and
-    board_type of entries in the board database until a match is found.
-
-    Args:
-        slug: the J-Link slug to look up in the database.
-
-    Raises:
-        UnknownBoard: a board matching the slug was not found.
-    """
-    matched_slug = slug.casefold()
-    return get_board(
-        lambda board: any(matched_slug == c.casefold() for c in [board.slug, board.board_name, board.board_type])
-    )
-
-
-def get_board(matching: Callable) -> Board:
-    """Returns first `mbed_tools.targets.board.Board` for which `matching` is True.
-
-    Uses database mode configured in the environment.
-
-    Args:
-        matching: A function which will be called to test matching conditions for each board in database.
-
-    Raises:
-        UnknownBoard: a board matching the criteria could not be found in the board database.
-    """
-    database_mode = _get_database_mode()
-
-    if database_mode == _DatabaseMode.OFFLINE:
-        logger.info("Using the offline database (only) to identify boards.")
-        return Boards.from_offline_database().get_board(matching)
-
-    if database_mode == _DatabaseMode.ONLINE:
-        logger.info("Using the online database (only) to identify boards.")
-        return Boards.from_online_database().get_board(matching)
-    try:
-        logger.info("Using the offline database to identify boards.")
-        return Boards.from_offline_database().get_board(matching)
-    except UnknownBoard:
-        logger.info("Unable to identify a board using the offline database, trying the online database.")
-        try:
-            return Boards.from_online_database().get_board(matching)
-        except BoardDatabaseError:
-            logger.error("Unable to access the online database to identify a board.")
-            raise UnknownBoard()
-
-
-class _DatabaseMode(Enum):
-    """Selected database mode."""
-
-    OFFLINE = 0
-    ONLINE = 1
-    AUTO = 2
-
-
-def _get_database_mode() -> _DatabaseMode:
-    database_mode = env.MBED_DATABASE_MODE
-    try:
-        return _DatabaseMode[database_mode]
-    except KeyError:
-        raise UnsupportedMode(f"{database_mode} is not a supported database mode.")
-
-
-
-
-
-
-
-

Functions

-
-
-def get_board(matching: Callable) ‑> Board -
-
-

Returns first Board for which matching is True.

-

Uses database mode configured in the environment.

-

Args

-
-
matching
-
A function which will be called to test matching conditions for each board in database.
-
-

Raises

-
-
UnknownBoard
-
a board matching the criteria could not be found in the board database.
-
-
- -Expand source code - -
def get_board(matching: Callable) -> Board:
-    """Returns first `mbed_tools.targets.board.Board` for which `matching` is True.
-
-    Uses database mode configured in the environment.
-
-    Args:
-        matching: A function which will be called to test matching conditions for each board in database.
-
-    Raises:
-        UnknownBoard: a board matching the criteria could not be found in the board database.
-    """
-    database_mode = _get_database_mode()
-
-    if database_mode == _DatabaseMode.OFFLINE:
-        logger.info("Using the offline database (only) to identify boards.")
-        return Boards.from_offline_database().get_board(matching)
-
-    if database_mode == _DatabaseMode.ONLINE:
-        logger.info("Using the online database (only) to identify boards.")
-        return Boards.from_online_database().get_board(matching)
-    try:
-        logger.info("Using the offline database to identify boards.")
-        return Boards.from_offline_database().get_board(matching)
-    except UnknownBoard:
-        logger.info("Unable to identify a board using the offline database, trying the online database.")
-        try:
-            return Boards.from_online_database().get_board(matching)
-        except BoardDatabaseError:
-            logger.error("Unable to access the online database to identify a board.")
-            raise UnknownBoard()
-
-
- -
-

Returns first mbed-tools.targets.board.Board matching given slug.

-

With J-Link, the slug is extracted from a board manufacturer URL, and may not match -the Mbed slug. The J-Link slug is compared against the slug, board_name and -board_type of entries in the board database until a match is found.

-

Args

-
-
slug
-
the J-Link slug to look up in the database.
-
-

Raises

-
-
UnknownBoard
-
a board matching the slug was not found.
-
-
- -Expand source code - -
def get_board_by_jlink_slug(slug: str) -> Board:
-    """Returns first `mbed-tools.targets.board.Board` matching given slug.
-
-    With J-Link, the slug is extracted from a board manufacturer URL, and may not match
-    the Mbed slug. The J-Link slug is compared against the slug, board_name and
-    board_type of entries in the board database until a match is found.
-
-    Args:
-        slug: the J-Link slug to look up in the database.
-
-    Raises:
-        UnknownBoard: a board matching the slug was not found.
-    """
-    matched_slug = slug.casefold()
-    return get_board(
-        lambda board: any(matched_slug == c.casefold() for c in [board.slug, board.board_name, board.board_type])
-    )
-
-
-
-def get_board_by_online_id(slug: str, target_type: str) ‑> Board -
-
-

Returns first Board matching given online id.

-

Args

-
-
slug
-
The slug to look up in the database.
-
target_type
-
The target type to look up in the database, normally one of platform or module.
-
-

Raises

-
-
UnknownBoard
-
a board with a matching slug and target type could not be found.
-
-
- -Expand source code - -
def get_board_by_online_id(slug: str, target_type: str) -> Board:
-    """Returns first `mbed_tools.targets.board.Board` matching given online id.
-
-    Args:
-        slug: The slug to look up in the database.
-        target_type: The target type to look up in the database, normally one of `platform` or `module`.
-
-    Raises:
-        UnknownBoard: a board with a matching slug and target type could not be found.
-    """
-    matched_slug = slug.casefold()
-    return get_board(lambda board: board.slug.casefold() == matched_slug and board.target_type == target_type)
-
-
-
-def get_board_by_product_code(product_code: str) ‑> Board -
-
-

Returns first Board matching given product code.

-

Args

-
-
product_code
-
the product code to look up in the database.
-
-

Raises

-
-
UnknownBoard
-
a board with a matching product code was not found.
-
-
- -Expand source code - -
def get_board_by_product_code(product_code: str) -> Board:
-    """Returns first `mbed_tools.targets.board.Board` matching given product code.
-
-    Args:
-        product_code: the product code to look up in the database.
-
-    Raises:
-        UnknownBoard: a board with a matching product code was not found.
-    """
-    return get_board(lambda board: board.product_code == product_code)
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/targets/get_target.html b/docs/api/targets/get_target.html deleted file mode 100644 index b05d6ef8..00000000 --- a/docs/api/targets/get_target.html +++ /dev/null @@ -1,191 +0,0 @@ - - - - - - -mbed_tools.targets.get_target API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.targets.get_target

-
-
-

Interface for accessing Targets from Mbed OS's targets.json.

-

An instance of mbed_tools.targets.target.Target -can be retrieved by calling one of the public functions.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""Interface for accessing Targets from Mbed OS's targets.json.
-
-An instance of `mbed_tools.targets.target.Target`
-can be retrieved by calling one of the public functions.
-"""
-from mbed_tools.targets.exceptions import TargetError
-from mbed_tools.targets._internal import target_attributes
-
-
-def get_target_by_name(name: str, targets_json_data: dict) -> dict:
-    """Returns a dictionary of attributes for the target whose name matches the name given.
-
-    The target is as defined in the targets.json file found in the Mbed OS library.
-
-    Args:
-        name: the name of the Target to be returned
-        targets_json_data: target definitions from targets.json
-
-    Raises:
-        TargetError: an error has occurred while fetching target
-    """
-    try:
-        return target_attributes.get_target_attributes(targets_json_data, name)
-    except (FileNotFoundError, target_attributes.TargetAttributesError) as e:
-        raise TargetError(e) from e
-
-
-def get_target_by_board_type(board_type: str, targets_json_data: dict) -> dict:
-    """Returns the target whose name matches a board's build_type.
-
-    The target is as defined in the targets.json file found in the Mbed OS library.
-
-    Args:
-        board_type: a board's board_type (see `mbed_tools.targets.board.Board`)
-        targets_json_data: target definitions from targets.json
-
-    Raises:
-        TargetError: an error has occurred while fetching target
-    """
-    return get_target_by_name(board_type, targets_json_data)
-
-
-
-
-
-
-
-

Functions

-
-
-def get_target_by_board_type(board_type: str, targets_json_data: dict) ‑> dict -
-
-

Returns the target whose name matches a board's build_type.

-

The target is as defined in the targets.json file found in the Mbed OS library.

-

Args

-
-
board_type
-
a board's board_type (see Board)
-
targets_json_data
-
target definitions from targets.json
-
-

Raises

-
-
TargetError
-
an error has occurred while fetching target
-
-
- -Expand source code - -
def get_target_by_board_type(board_type: str, targets_json_data: dict) -> dict:
-    """Returns the target whose name matches a board's build_type.
-
-    The target is as defined in the targets.json file found in the Mbed OS library.
-
-    Args:
-        board_type: a board's board_type (see `mbed_tools.targets.board.Board`)
-        targets_json_data: target definitions from targets.json
-
-    Raises:
-        TargetError: an error has occurred while fetching target
-    """
-    return get_target_by_name(board_type, targets_json_data)
-
-
-
-def get_target_by_name(name: str, targets_json_data: dict) ‑> dict -
-
-

Returns a dictionary of attributes for the target whose name matches the name given.

-

The target is as defined in the targets.json file found in the Mbed OS library.

-

Args

-
-
name
-
the name of the Target to be returned
-
targets_json_data
-
target definitions from targets.json
-
-

Raises

-
-
TargetError
-
an error has occurred while fetching target
-
-
- -Expand source code - -
def get_target_by_name(name: str, targets_json_data: dict) -> dict:
-    """Returns a dictionary of attributes for the target whose name matches the name given.
-
-    The target is as defined in the targets.json file found in the Mbed OS library.
-
-    Args:
-        name: the name of the Target to be returned
-        targets_json_data: target definitions from targets.json
-
-    Raises:
-        TargetError: an error has occurred while fetching target
-    """
-    try:
-        return target_attributes.get_target_attributes(targets_json_data, name)
-    except (FileNotFoundError, target_attributes.TargetAttributesError) as e:
-        raise TargetError(e) from e
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/docs/api/targets/index.html b/docs/api/targets/index.html deleted file mode 100644 index 9549866a..00000000 --- a/docs/api/targets/index.html +++ /dev/null @@ -1,140 +0,0 @@ - - - - - - -mbed_tools.targets API documentation - - - - - - - - - - - -
-
-
-

Module mbed_tools.targets

-
-
-

An abstraction layer describing hardware supported by Mbed OS.

-

Querying Board Database

-

For the interface to query board database, look at mbed_tools.targets.get_board.

-

Fetching target data

-
-

For the interface to extract target data from their definitions in Mbed OS, -look at mbed_tools.targets.get_target.

-

Configuration

-

For details about configuration of this module, look at mbed_tools.targets.config.

-
- -Expand source code - -
#
-# Copyright (c) 2020-2021 Arm Limited and Contributors. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-"""An abstraction layer describing hardware supported by Mbed OS.
-
-Querying board database
------------------------
-
-For the interface to query board database, look at `mbed_tools.targets.get_board`.
-
-Fetching target data
-____________________
-
-For the interface to extract target data from their definitions in Mbed OS,
-look at `mbed_tools.targets.get_target`.
-
-Configuration
--------------
-
-For details about configuration of this module, look at `mbed_tools.targets.config`.
-"""
-from mbed_tools.targets import exceptions
-from mbed_tools.targets.get_target import (
-    get_target_by_name,
-    get_target_by_board_type,
-)
-from mbed_tools.targets.get_board import (
-    get_board_by_product_code,
-    get_board_by_online_id,
-    get_board_by_jlink_slug,
-)
-from mbed_tools.targets.board import Board
-
-
-
-

Sub-modules

-
-
mbed_tools.targets.board
-
-

Representation of an Mbed-Enabled Development Board and related utilities.

-
-
mbed_tools.targets.boards
-
-

Interface to the Board Database.

-
-
mbed_tools.targets.env
-
-

Environment options for mbed-targets …

-
-
mbed_tools.targets.exceptions
-
-

Public exceptions exposed by the package.

-
-
mbed_tools.targets.get_board
-
-

Interface for accessing Mbed-Enabled Development Board data …

-
-
mbed_tools.targets.get_target
-
-

Interface for accessing Targets from Mbed OS's targets.json …

-
-
-
-
-
-
-
-
-
-
- -
- - - \ No newline at end of file diff --git a/news/202203251430.misc b/news/202203251430.misc new file mode 100644 index 00000000..c29572f9 --- /dev/null +++ b/news/202203251430.misc @@ -0,0 +1 @@ +Remove pdoc3 and generated documentation diff --git a/pyproject.toml b/pyproject.toml index 92c0d1c2..c67930b5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -18,8 +18,6 @@ NEWS_DIR = "news/" SOURCE_DIR = "src/mbed_tools" RELEASE_BRANCH_PATTERN = "^release.*$" MODULE_TO_DOCUMENT = "mbed_tools" -DOCUMENTATION_DEFAULT_OUTPUT_PATH = "local_docs" -DOCUMENTATION_PRODUCTION_OUTPUT_PATH = "docs/api" CHANGELOG_FILE_PATH = "CHANGELOG.md" [tool.setuptools_scm] diff --git a/setup.py b/setup.py index bdababbe..7d147a18 100644 --- a/setup.py +++ b/setup.py @@ -38,7 +38,6 @@ install_requires=[ "python-dotenv", "Click>=7.1,<8", - "pdoc3", "GitPython", "tqdm", "tabulate", diff --git a/src/mbed_tools/targets/env.py b/src/mbed_tools/targets/env.py index c9f71f3b..ddf4afc9 100644 --- a/src/mbed_tools/targets/env.py +++ b/src/mbed_tools/targets/env.py @@ -21,7 +21,6 @@ import os import dotenv -import pdoc dotenv.load_dotenv(dotenv.find_dotenv(usecwd=True)) @@ -30,8 +29,6 @@ class Env: """Provides access to environment variables. Ensures variables are reloaded when environment changes during runtime. - Additionally allows to expose documented instance variables in pdoc - generated output. """ @property @@ -72,5 +69,3 @@ def MBED_DATABASE_MODE(self) -> str: env = Env() """Instance of `Env` class.""" - -env_variables = pdoc.Class("Env", pdoc.Module("mbed_tools.targets.env"), Env).instance_variables() diff --git a/tox.ini b/tox.ini index 141662d9..9b708923 100644 --- a/tox.ini +++ b/tox.ini @@ -30,11 +30,6 @@ deps = towncrier commands = python -m towncrier.check -[testenv:generatedocs] -deps = - mbed-tools-ci-scripts -commands = generate-docs --output_dir {posargs} - [testenv:preprelease] usedevelop = True allowlist_externals = git From 45837719b1414458fbcdd6990456736cb599c402 Mon Sep 17 00:00:00 2001 From: Monty Bot Date: Tue, 14 Jun 2022 10:35:49 +0000 Subject: [PATCH 2/8] Prepare mbed-tools release 7.54.0 --- CHANGELOG.md | 15 +++++++++++++++ news/202203251430.misc | 1 - .../_internal/data/board_database_snapshot.json | 15 ++++++++++++++- 3 files changed, 29 insertions(+), 2 deletions(-) delete mode 100644 news/202203251430.misc diff --git a/CHANGELOG.md b/CHANGELOG.md index d0fbf32f..6bb72759 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,21 @@ beta releases are not included in this history. For a full list of all releases, [//]: # (begin_release_notes) +7.54.0 (2022-06-14) +=================== + +Features +-------- + +- Targets modified: NUCLEO-H7A3ZI-Q. (#20220614103546) + + +Misc +---- + +- #202203251430 + + 7.53.0 (2022-03-22) =================== diff --git a/news/202203251430.misc b/news/202203251430.misc deleted file mode 100644 index c29572f9..00000000 --- a/news/202203251430.misc +++ /dev/null @@ -1 +0,0 @@ -Remove pdoc3 and generated documentation diff --git a/src/mbed_tools/targets/_internal/data/board_database_snapshot.json b/src/mbed_tools/targets/_internal/data/board_database_snapshot.json index 0da76c73..4ab50d48 100644 --- a/src/mbed_tools/targets/_internal/data/board_database_snapshot.json +++ b/src/mbed_tools/targets/_internal/data/board_database_snapshot.json @@ -1267,7 +1267,20 @@ "target_type": "platform", "slug": "ST-Nucleo-H7A3ZI-Q", "build_variant": [], - "mbed_os_support": [], + "mbed_os_support": [ + "Mbed OS 6.10", + "Mbed OS 6.11", + "Mbed OS 6.12", + "Mbed OS 6.13", + "Mbed OS 6.14", + "Mbed OS 6.15", + "Mbed OS 6.4", + "Mbed OS 6.5", + "Mbed OS 6.6", + "Mbed OS 6.7", + "Mbed OS 6.8", + "Mbed OS 6.9" + ], "mbed_enabled": [] }, { From 20cd704874bfa96fa8dd794b49e92fc8baea0d35 Mon Sep 17 00:00:00 2001 From: Monty Bot Date: Sat, 2 Jul 2022 05:01:35 +0000 Subject: [PATCH 3/8] Prepare mbed-tools release 7.55.0 --- CHANGELOG.md | 9 +++++++ .../data/board_database_snapshot.json | 24 +++++++++++++++++++ 2 files changed, 33 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6bb72759..75ae5c61 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,15 @@ beta releases are not included in this history. For a full list of all releases, [//]: # (begin_release_notes) +7.55.0 (2022-07-02) +=================== + +Features +-------- + +- Targets added: AdBun-M4GR, AdBun-M4NR. (#20220702050132) + + 7.54.0 (2022-06-14) =================== diff --git a/src/mbed_tools/targets/_internal/data/board_database_snapshot.json b/src/mbed_tools/targets/_internal/data/board_database_snapshot.json index 4ab50d48..177c5f30 100644 --- a/src/mbed_tools/targets/_internal/data/board_database_snapshot.json +++ b/src/mbed_tools/targets/_internal/data/board_database_snapshot.json @@ -298,6 +298,30 @@ ], "mbed_enabled": [] }, + { + "board_type": "TMPM4NR", + "board_name": "AdBun-M4NR", + "product_code": "7022", + "target_type": "platform", + "slug": "TMPM4NR", + "build_variant": [], + "mbed_os_support": [ + "Mbed OS 6.9" + ], + "mbed_enabled": [] + }, + { + "board_type": "TMPM4GR", + "board_name": "AdBun-M4GR", + "product_code": "7021", + "target_type": "platform", + "slug": "TMPM4GR", + "build_variant": [], + "mbed_os_support": [ + "Mbed OS 6.9" + ], + "mbed_enabled": [] + }, { "board_type": "NUCLEO_H563ZI", "board_name": "NUCLEO-H563ZI", From 14343ca1f39c7c90910e203b798d9a5b3d6d1944 Mon Sep 17 00:00:00 2001 From: ATmobica Date: Wed, 20 Jul 2022 14:34:00 +0200 Subject: [PATCH 4/8] config: Increase version of click and black packages The latest version (8.1.3) of the click package is supported in many projects. E.g. in CHIP project where mbed-os port is implemented. https://github.com/project-chip/connectedhomeip In this case, we need to increase the limit of the click version to 8.1. We need to also update the black package version to be compatible with the click. These changes required fix in TestNewCommand class. We need to use `Path().resolve()` which is also use in latest click implementation. Signed-off-by: ATmobica --- .pre-commit-config.yaml | 2 +- news/2022072013030.misc | 1 + setup.py | 2 +- tests/cli/test_project_management.py | 4 ++-- 4 files changed, 5 insertions(+), 4 deletions(-) create mode 100644 news/2022072013030.misc diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 95f978b9..2f4220bb 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,6 +1,6 @@ repos: - repo: https://github.com/psf/black - rev: 19.10b0 + rev: 22.6.0 hooks: - id: black diff --git a/news/2022072013030.misc b/news/2022072013030.misc new file mode 100644 index 00000000..7b31cf4b --- /dev/null +++ b/news/2022072013030.misc @@ -0,0 +1 @@ +Increase version of click and black packages diff --git a/setup.py b/setup.py index 7d147a18..93a39b05 100644 --- a/setup.py +++ b/setup.py @@ -37,7 +37,7 @@ include_package_data=True, install_requires=[ "python-dotenv", - "Click>=7.1,<8", + "Click>=7.1,<9", "GitPython", "tqdm", "tabulate", diff --git a/tests/cli/test_project_management.py b/tests/cli/test_project_management.py index 6edfc8bb..48708e97 100644 --- a/tests/cli/test_project_management.py +++ b/tests/cli/test_project_management.py @@ -41,13 +41,13 @@ def mock_get_libs(): class TestNewCommand: def test_calls_new_function_with_correct_args(self, mock_initialise_project): CliRunner().invoke(new, ["path", "--create-only"]) - mock_initialise_project.assert_called_once_with(pathlib.Path.cwd() / "path", True) + mock_initialise_project.assert_called_once_with(pathlib.Path("path").resolve(), True) def test_echos_mbed_os_message_when_required(self, mock_initialise_project): expected = ( "Creating a new Mbed program at path " + "'" - + str(pathlib.Path.cwd() / "path") + + str(pathlib.Path("path").resolve()) + "'" + ".\nDownloading mbed-os and adding it to the project.\n" ) From c2002edd537418084c4c618b11a20f866fadbaf7 Mon Sep 17 00:00:00 2001 From: Monty Bot Date: Sat, 27 Aug 2022 05:01:07 +0000 Subject: [PATCH 5/8] Prepare mbed-tools release 7.56.0 --- CHANGELOG.md | 16 ++++++++++++++++ news/2022072013030.misc | 1 - .../_internal/data/board_database_snapshot.json | 2 +- 3 files changed, 17 insertions(+), 2 deletions(-) delete mode 100644 news/2022072013030.misc diff --git a/CHANGELOG.md b/CHANGELOG.md index 75ae5c61..03f9b3e3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,22 @@ beta releases are not included in this history. For a full list of all releases, [//]: # (begin_release_notes) +7.56.0 (2022-08-27) +=================== + +Features +-------- + +- Targets added: SBK-M4NR development board. + Targets removed: AdBun-M4NR. (#20220827050103) + + +Misc +---- + +- #2022072013030 + + 7.55.0 (2022-07-02) =================== diff --git a/news/2022072013030.misc b/news/2022072013030.misc deleted file mode 100644 index 7b31cf4b..00000000 --- a/news/2022072013030.misc +++ /dev/null @@ -1 +0,0 @@ -Increase version of click and black packages diff --git a/src/mbed_tools/targets/_internal/data/board_database_snapshot.json b/src/mbed_tools/targets/_internal/data/board_database_snapshot.json index 177c5f30..d2f02f0c 100644 --- a/src/mbed_tools/targets/_internal/data/board_database_snapshot.json +++ b/src/mbed_tools/targets/_internal/data/board_database_snapshot.json @@ -300,7 +300,7 @@ }, { "board_type": "TMPM4NR", - "board_name": "AdBun-M4NR", + "board_name": "SBK-M4NR development board", "product_code": "7022", "target_type": "platform", "slug": "TMPM4NR", From 6128c16927d350278e9bec1ff539d85d31a4c81f Mon Sep 17 00:00:00 2001 From: Monty Bot Date: Fri, 2 Sep 2022 05:01:16 +0000 Subject: [PATCH 6/8] Prepare mbed-tools release 7.57.0 --- CHANGELOG.md | 9 +++++++++ .../targets/_internal/data/board_database_snapshot.json | 2 +- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 03f9b3e3..d6e61d6f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,15 @@ beta releases are not included in this history. For a full list of all releases, [//]: # (begin_release_notes) +7.57.0 (2022-09-02) +=================== + +Features +-------- + +- Targets modified: SBK-M4NR development board. (#20220902050111) + + 7.56.0 (2022-08-27) =================== diff --git a/src/mbed_tools/targets/_internal/data/board_database_snapshot.json b/src/mbed_tools/targets/_internal/data/board_database_snapshot.json index d2f02f0c..d06dcfd9 100644 --- a/src/mbed_tools/targets/_internal/data/board_database_snapshot.json +++ b/src/mbed_tools/targets/_internal/data/board_database_snapshot.json @@ -306,7 +306,7 @@ "slug": "TMPM4NR", "build_variant": [], "mbed_os_support": [ - "Mbed OS 6.9" + "Mbed OS 6.15" ], "mbed_enabled": [] }, From ad903d0399b4236dd51f8ac79dfbafce65d7d2df Mon Sep 17 00:00:00 2001 From: Monty Bot Date: Thu, 27 Oct 2022 05:01:07 +0000 Subject: [PATCH 7/8] Prepare mbed-tools release 7.58.0 --- CHANGELOG.md | 9 +++++++++ .../targets/_internal/data/board_database_snapshot.json | 2 +- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d6e61d6f..d845a7d8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,15 @@ beta releases are not included in this history. For a full list of all releases, [//]: # (begin_release_notes) +7.58.0 (2022-10-27) +=================== + +Features +-------- + +- Targets modified: AdBun-M4GR. (#20221027050103) + + 7.57.0 (2022-09-02) =================== diff --git a/src/mbed_tools/targets/_internal/data/board_database_snapshot.json b/src/mbed_tools/targets/_internal/data/board_database_snapshot.json index d06dcfd9..2619d094 100644 --- a/src/mbed_tools/targets/_internal/data/board_database_snapshot.json +++ b/src/mbed_tools/targets/_internal/data/board_database_snapshot.json @@ -318,7 +318,7 @@ "slug": "TMPM4GR", "build_variant": [], "mbed_os_support": [ - "Mbed OS 6.9" + "Mbed OS 6.15" ], "mbed_enabled": [] }, From 7ff8ed4d57857805bbf9f2b79486fdc3440dee9f Mon Sep 17 00:00:00 2001 From: Monty Bot Date: Wed, 16 Nov 2022 05:01:07 +0000 Subject: [PATCH 8/8] Prepare mbed-tools release 7.59.0 --- CHANGELOG.md | 10 ++++++++++ .../_internal/data/board_database_snapshot.json | 2 +- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d845a7d8..bb184037 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,16 @@ beta releases are not included in this history. For a full list of all releases, [//]: # (begin_release_notes) +7.59.0 (2022-11-16) +=================== + +Features +-------- + +- Targets added: AdBun-M4NR development board. + Targets removed: SBK-M4NR development board. (#20221116050105) + + 7.58.0 (2022-10-27) =================== diff --git a/src/mbed_tools/targets/_internal/data/board_database_snapshot.json b/src/mbed_tools/targets/_internal/data/board_database_snapshot.json index 2619d094..55339905 100644 --- a/src/mbed_tools/targets/_internal/data/board_database_snapshot.json +++ b/src/mbed_tools/targets/_internal/data/board_database_snapshot.json @@ -300,7 +300,7 @@ }, { "board_type": "TMPM4NR", - "board_name": "SBK-M4NR development board", + "board_name": "AdBun-M4NR development board", "product_code": "7022", "target_type": "platform", "slug": "TMPM4NR",