plesty.sdk.commands.init

CLI command for initializing a new Plesty project from a template.

Attributes

MODULE_NAME_PATTERN

_STANDARD_CI_STAGES

PLESTY_LIB_VERSION

PLESTY_SDK_VERSION

PYPI_LIB_URL

PYPI_TIMEOUT_S

_LEAKING_GIT_VARS

Functions

_own_line_floor(→ str)

Return major.minor.0 of the installed plesty-sdk.

resolve_lib_version(→ str)

Return the newest plesty-lib on PyPI, or PLESTY_LIB_VERSION.

_parse_version(→ packaging.version.Version | None)

Return version parsed, or None when PyPI lists something unreadable.

lib_specifier(→ str)

Return the version specifier to write after plesty-lib in pyproject.

init_command(→ None)

Initialize a new Plesty project from a template.

_format_generated_files(→ None)

Run ruff format on generated Python files so the initial commit is already clean.

_git_initial_commit(→ None)

Stage all generated files and create an initial commit.

generate_gitlab_ci(→ None)

Write a .gitlab-ci.yml that uses the plesty-standard-ci CI component.

_echo_next_steps(→ None)

Echo the concrete next steps for a freshly scaffolded project.

_install_pre_push_hook(→ None)

Write a pre-push git hook that runs plesty check.

_copy_extras(→ None)

Copy type-specific extra files into the generated module directory.

Module Contents

plesty.sdk.commands.init.MODULE_NAME_PATTERN
plesty.sdk.commands.init._STANDARD_CI_STAGES = ('check', 'security', 'deploy', 'release')
plesty.sdk.commands.init.PLESTY_LIB_VERSION = '0.5.1'
plesty.sdk.commands.init._own_line_floor() → str

Return major.minor.0 of the installed plesty-sdk.

A scaffold is written against the gates and the plesty init field-test interview of the SDK generating it, so the pin names that SDK’s own line. A hand-kept constant went stale: 0.4 and 0.5 still pinned 0.3.4, which lacks the gates their scaffolds rely on.

Return type:

str

plesty.sdk.commands.init.PLESTY_SDK_VERSION
plesty.sdk.commands.init.PYPI_LIB_URL = 'https://pypi.org/pypi/plesty-lib/json'
plesty.sdk.commands.init.PYPI_TIMEOUT_S = 3.0
plesty.sdk.commands.init.resolve_lib_version(url: str = PYPI_LIB_URL, timeout: float = PYPI_TIMEOUT_S) → str

Return the newest plesty-lib on PyPI, or PLESTY_LIB_VERSION.

A scaffold should start on the library that exists today, not on the one that existed when this SDK was released — the pin is what a new module lives with until someone edits it. Pre-releases count: the development line is where the features the templates use land first, and a pin naming a .devN is what makes them resolvable at all.

Anything the network does wrong — no route, a proxy, a timeout, a body that is not the JSON expected — falls back to the built-in floor rather than failing the scaffold. The answer is never older than that floor.

Parameters:

  • url (str) – PyPI JSON endpoint for the package.

  • timeout (float) – Seconds to wait for it.

Returns:

The version string to pin with >=.

Return type:

str

plesty.sdk.commands.init._parse_version(version: str) → packaging.version.Version | None

Return version parsed, or None when PyPI lists something unreadable.

Parameters:

version (str)

Return type:

packaging.version.Version | None

plesty.sdk.commands.init.lib_specifier(requested: str | None = None) → str

Return the version specifier to write after plesty-lib in pyproject.

Without requested the pin follows PyPI (resolve_lib_version()). With it, the caller decides and no lookup happens — a tutorial pins the library its lesson text was written against, so the page and the file the reader ends up with keep saying the same thing however far the library has moved since; an air-gapped machine gets the same determinism.

Parameters:

requested (str | None) – A bare version ("0.3.5.dev3" → ">=0.3.5.dev3") or a complete specifier, which is taken as written ("==0.4.0", ">=0.3.5.dev3,<0.4").

Returns:

The specifier, leading operator included.

Raises:

click.ClickException – If requested is neither a version nor a specifier PEP 440 can read.

Return type:

str

plesty.sdk.commands.init.init_command(context: plesty.sdk.context.ApplicationContext, project_type: str, module_name: str | None, author: str | None, email: str | None, standard: str, lib_version: str | None, no_ci: bool, force: bool) → None

Initialize a new Plesty project from a template.

PROJECT_TYPE is one of: default, device, analyzer, experiment. Defaults to ‘default’.

Two project types add to an existing device module rather than creating a project. plesty init field-test reads what the device declares and asks the developer to classify what no inspection can answer — which operations are safe unattended, which parameters survive being written back their own value, what is slow enough to interrupt — then writes tests/field_test.py with the answers and the reasons recorded as comments. plesty init mock-test asks nothing: it probes the module for a construction that runs without hardware, verifies it against the gates it will have to pass, and writes the hardware-free test gate d1 requires.

Conventions:

  • Project folder: plesty-foo-bar

  • Src code folder: foo_bar

  • Build target: plesty-foo-bar

  • Import: plesty.foo_bar

The project is created in the directory set via the global –project-dir option (defaults to the current working directory). If the directory does not yet exist it is created; if it already exists it must be empty (hidden entries such as .git are ignored).

The –name option sets the Python module name (snake_case). When omitted, the name is inferred from the project directory name: the ‘plesty-’ prefix is stripped and remaining hyphens are converted to underscores (e.g. ‘plesty-foo-bar’ → ‘foo_bar’).

Parameters:

  • context (plesty.sdk.context.ApplicationContext)

  • project_type (str)

  • module_name (str | None)

  • author (str | None)

  • email (str | None)

  • standard (str)

  • lib_version (str | None)

  • no_ci (bool)

  • force (bool)

Return type:

None

plesty.sdk.commands.init._format_generated_files(project_dir: pathlib.Path) → None

Run ruff format on generated Python files so the initial commit is already clean.

Failures are silently ignored — formatting is best-effort at scaffold time.

Parameters:

project_dir (pathlib.Path)

Return type:

None

plesty.sdk.commands.init._git_initial_commit(project_dir: pathlib.Path) → None

Stage all generated files and create an initial commit.

versioningit needs at least one commit to resolve a version from git history. Always initialises a git repo in project_dir so we never accidentally operate on a parent repo when the project lives inside a workspace.

Parameters:

project_dir (pathlib.Path)

Return type:

None

plesty.sdk.commands.init.generate_gitlab_ci(project_dir: pathlib.Path, standard: str = 'quantum') → None

Write a .gitlab-ci.yml that uses the plesty-standard-ci CI component.

Parameters:

  • project_dir (pathlib.Path)

  • standard (str)

Return type:

None

plesty.sdk.commands.init._echo_next_steps(project_type: str, module_name: str) → None

Echo the concrete next steps for a freshly scaffolded project.

The step text lives in the packaged assets/init/next-steps.yaml: setup steps first, then the project-type-specific ones, then verify. {module_name} placeholders are substituted here.

Parameters:

  • project_type (str) – The scaffolded project type (default/device/experiment).

  • module_name (str) – The Python module name of the new project.

Return type:

None

plesty.sdk.commands.init._LEAKING_GIT_VARS = ('GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_PREFIX', 'GIT_COMMON_DIR')
plesty.sdk.commands.init._install_pre_push_hook(project_dir: pathlib.Path, quiet: bool = False) → None

Write a pre-push git hook that runs plesty check.

The standard is read from [tool.plesty] standard in pyproject.toml; when unset it is derived from the release version (<0.1 pixel, <1.0 nebula, >=1.0 quantum), so a module’s pre-push enforcement ramps up with its releases.

The hook clears the git variables the hook environment carries; see _LEAKING_GIT_VARS for what they break.

Parameters:

  • project_dir (pathlib.Path)

  • quiet (bool)

Return type:

None

plesty.sdk.commands.init._copy_extras(extras_src: pathlib.Path, dest: pathlib.Path) → None

Copy type-specific extra files into the generated module directory.

Parameters:

  • extras_src (pathlib.Path)

  • dest (pathlib.Path)

Return type:

None