wads.profiles

Declarative generation profiles and overlays built on the engine.

A profile is a named declarative description of a project setup expressed as a list of wads.templating.Artifact. The default profile (python-lib) is produced by wads.populate.

This module hosts two opt-in overlays added on top of an existing project:

• The frontend profile registry (issue #39): a small registry of language/toolchain profiles – js (the original #32 overlay, the back-compat anchor), ts (single-package TypeScript), and ts-monorepo (pnpm workspaces + turbo). A project may declare several frontend components (e.g. js and ts); each lives in its own subdir with its own path-filtered workflow, so they never collide. Selected via populate --frontend <profile>[,<profile>] (--with-npm stays as an alias for --frontend js). Profiles are extensible through register_frontend_profile().

• The tests-folder overlay (issue #4): scaffolds a tests/ package.

Nothing here runs by default; the Python populate path and the name/name/ root layout are untouched.

Module Attributes

FRONTEND_PROFILES

The frontend profile registry.

Functions

apply_frontend(pkg_dir, *[, profile, ...])	Apply one frontend profile component to an existing project directory.
apply_npm_overlay(pkg_dir, *, project_name)	Deprecated alias for apply_frontend(profile="js", ...) (issue #32 surface).
apply_tests_overlay(pkg_dir, *, project_name)	Scaffold a tests/ folder in an existing project (issue #4).
frontend_context(*, profile_name, project_name)	Build the render context shared by all frontend-profile templates.
get_frontend_profile(name)	Look up a registered profile, with an informative error if unknown.
make_tests_overlay_artifacts(project_name, *)	Artifacts that scaffold a tests/ folder for a project.
npm_overlay_artifacts([npm_subdir])	Deprecated: the js overlay artifacts.
npm_overlay_context(*, project_name[, ...])	Deprecated: render context for the js overlay.
register_frontend_profile(profile)	Register (or override) a frontend profile by name.

Classes

FrontendProfile(name, default_subdir, ...[, ...])

A declarative frontend language/toolchain profile.

wads.profiles.FRONTEND_PROFILES: dict = {'js': FrontendProfile(name='js', default_subdir='js', default_package_manager='npm', artifacts=<function _js_artifacts>, description='JavaScript single package (the original #32 overlay).'), 'ts': FrontendProfile(name='ts', default_subdir='ts', default_package_manager='npm', artifacts=<function _ts_artifacts>, description='TypeScript single package (tsconfig + tsup build + vitest).'), 'ts-monorepo': FrontendProfile(name='ts-monorepo', default_subdir='ts', default_package_manager='pnpm', artifacts=<function _ts_monorepo_artifacts>, description='TypeScript monorepo (pnpm workspaces + turbo).')}

The frontend profile registry. Extend it via register_frontend_profile().

class wads.profiles.FrontendProfile(name, default_subdir, default_package_manager, artifacts, description='')

Bases: object

A declarative frontend language/toolchain profile.

Parameters:

• name (str) – registry key (e.g. "js", "ts", "ts-monorepo").

• default_subdir (str) – subdir the component lives in when unspecified.

• default_package_manager (str) – "npm" or "pnpm".

• artifacts (Callable[[Mapping], list]) – context -> list[Artifact] builder for this profile.

• description (str) – one-line human summary.

wads.profiles.apply_frontend(pkg_dir, *, profile='js', project_name, description='', license=None, subdir=None, package_name=None, version='0.0.1', package_manager=None, workspace_glob='packages/*', example_package_name=None, overwrite=(), on_add=None, on_skip=None)

Apply one frontend profile component to an existing project directory.

subdir and package_manager default to the selected profile’s defaults. Returns the wads.templating.GenerationResult.

Return type:

GenerationResult

>>> import tempfile
>>> d = tempfile.mkdtemp()
>>> res = apply_frontend(d, profile="ts", project_name="widget")
>>> sorted(res.added)
['.github/workflows/npm-ci-ts.yml', 'ts/package.json', 'ts/src/index.test.ts',
 'ts/src/index.ts', 'ts/tsconfig.json']

wads.profiles.apply_npm_overlay(pkg_dir, *, project_name, description='', license=None, npm_subdir='js', npm_package_name=None, npm_version='0.0.1', npm_package_manager='npm', overwrite=(), on_add=None, on_skip=None)

Deprecated alias for apply_frontend(profile="js", ...) (issue #32 surface).

Kept so existing callers and tests keep working; new code should call apply_frontend().

wads.profiles.apply_tests_overlay(pkg_dir, *, project_name, with_data_util=True, overwrite=(), on_add=None, on_skip=None)

Scaffold a tests/ folder in an existing project (issue #4).

wads.profiles.frontend_context(*, profile_name, project_name, description='', license=None, subdir, package_name=None, version='0.0.1', package_manager='npm', workspace_glob='packages/*', example_package_name=None)

Build the render context shared by all frontend-profile templates.

The returned mapping is a superset: it carries the keys every profile’s templates may reference (single-package and monorepo). Unused keys are harmless under Jinja StrictUndefined because that only errors on keys a template references yet are missing.

Return type:

dict

wads.profiles.get_frontend_profile(name)

Look up a registered profile, with an informative error if unknown.

Return type:

FrontendProfile

wads.profiles.make_tests_overlay_artifacts(project_name, *, with_data_util=True)

Artifacts that scaffold a tests/ folder for a project.

Writes tests/__init__.py, tests/test_<project_name>.py (a smoke test), and optionally tests/util.py (a tests/data accessor, per #4). The smoke-test filename embeds the package name, so it is built here where the name is known.

Return type:

list

wads.profiles.npm_overlay_artifacts(npm_subdir='js')

Deprecated: the js overlay artifacts. Use the js frontend profile.

Return type:

list

wads.profiles.npm_overlay_context(*, project_name, description='', license=None, npm_subdir='js', npm_package_name=None, npm_version='0.0.1', npm_package_manager='npm')

Deprecated: render context for the js overlay. Use apply_frontend().

Return type:

dict

wads.profiles.register_frontend_profile(profile)

Register (or override) a frontend profile by name. Returns the profile.

Return type:

FrontendProfile