Coverage for src/debputy/plugin/api/std_docs.py: 84%
17 statements
« prev ^ index » next coverage.py v7.8.2, created at 2026-04-19 20:37 +0000
1import textwrap
2from typing import Any
3from collections.abc import Sequence, Mapping, Container, Iterable
5from debputy.manifest_parser.base_types import DebputyParsedContentStandardConditional
6from debputy.manifest_parser.tagging_types import DebputyParsedContent
7from debputy.plugin.api.spec import (
8 ParserAttributeDocumentation,
9 StandardParserAttributeDocumentation,
10)
11from debputy.plugins.debputy.to_be_api_types import (
12 OptionalInstallDirectly,
13 OptionalInSourceBuild,
14 OptionalBuildDirectory,
15 BuildRuleParsedFormat,
16 OptionalTestRule,
17)
19_STD_ATTR_DOCS: Mapping[
20 type[DebputyParsedContent],
21 Sequence[ParserAttributeDocumentation],
22] = {
23 BuildRuleParsedFormat: [
24 StandardParserAttributeDocumentation(
25 frozenset(["name"]),
26 textwrap.dedent("""\
27 The name of the build step.
29 The name is used for multiple things, such as:
30 1) If you ever need to reference the build elsewhere, the name will be used.
31 2) When `debputy` references the build in log output and error, it will use the name.
32 3) It is used as defaults for when `debputy` derives build and `DESTDIR` directories
33 for the build.
34 """),
35 # Put in top,
36 sort_category=-1000,
37 ),
38 StandardParserAttributeDocumentation(
39 frozenset(["for_packages"]),
40 textwrap.dedent("""\
41 Which packages this build step applies to.
43 The value should be either a package name mentioned in `debian/control`,
44 a package selection (such as `arch:all` or `package-type:deb`), or
45 a list of these names or selections. The listed values should be a
46 subset of the binary packages listed in `debian/control`.
48 When the attribute is omitted, then the step applies to all packages
49 listed in `debian/control`.
51 This attribute enables 'debputy` to skip the build step when none of
52 the relevant packages are being built as well as provide defaults
53 (such as search directories for the `installations` feature)
54 """),
55 ),
56 StandardParserAttributeDocumentation(
57 frozenset(["environment"]),
58 textwrap.dedent("""\
59 Specify that this build step uses the named environment
61 If omitted, the default environment will be used. If no default environment is present,
62 then this option is mandatory.
63 """),
64 ),
65 ],
66 OptionalBuildDirectory: [
67 StandardParserAttributeDocumentation(
68 frozenset(["build_directory"]),
69 textwrap.dedent("""\
70 The build directory to use for the build.
72 By default, `debputy` will derive a build directory automatically if the build system needs
73 it. However, it can be useful if you need to reference the directory name from other parts
74 of the manifest or want a "better" name than `debputy` comes up with.
75 """),
76 ),
77 ],
78 OptionalInSourceBuild: [
79 StandardParserAttributeDocumentation(
80 frozenset(["perform_in_source_build"]),
81 textwrap.dedent("""\
82 Whether the build system should use "in source" or "out of source" build.
84 This is mostly useful for forcing "in source" builds for build systems that default to
85 "out of source" builds like `autoconf`.
87 The default depends on the build system and the value of the `build-directory` attribute
88 (if supported by the build system).
89 """),
90 # Late
91 sort_category=500,
92 ),
93 ],
94 OptionalInstallDirectly: [
95 StandardParserAttributeDocumentation(
96 frozenset(["install_directly_to_package"]),
97 textwrap.dedent("""\
98 Whether the build system should install all upstream content directly into the package.
100 This option is mostly useful for disabling said behavior by setting the attribute to `false`.
101 The attribute conditionally defaults to `true` when the build only applies to one package.
102 If explicitly set to `true`, then this build step must apply to exactly one package (usually
103 implying that `for` is set to that package when the source builds multiple packages).
105 When `true`, this behaves similar to `dh_auto_install --destdir=debian/PACKAGE`.
106 """),
107 ),
108 ],
109 OptionalTestRule: [
110 StandardParserAttributeDocumentation(
111 frozenset(["test_rule"]),
112 textwrap.dedent("""\
113 Whether to run tests at build time
115 When omitted, build time tests are run when the build system detects any provided
116 the builder has not skipped tests (by using DEB_BUILD_OPTIONS=nocheck, etc.).
117 """),
118 ),
119 ],
120 DebputyParsedContentStandardConditional: [
121 StandardParserAttributeDocumentation(
122 frozenset(["when"]),
123 textwrap.dedent("""\
124 A condition as defined in [Conditional rules](${MANIFEST_FORMAT_DOC}#conditional-rules).
126 The conditional will disable the entire rule when the conditional evaluates to false.
127 """),
128 # Last
129 sort_category=9999,
130 ),
131 ],
132}
135def docs_from(
136 *ts: Any,
137 exclude_attributes: Container[str] = frozenset(),
138) -> Iterable[ParserAttributeDocumentation]:
139 """Provide standard attribute documentation from existing types
141 This is a work-around for `apply_standard_attribute_documentation` requiring python3.12.
142 If you can assume python3.12, use `apply_standard_attribute_documentation` instead.
143 """
144 for t in ts:
145 attrs = _STD_ATTR_DOCS.get(t)
146 if attrs is None: 146 ↛ 147line 146 didn't jump to line 147 because the condition on line 146 was never true
147 raise ValueError(f"No standard documentation for {str(t)}")
148 for attr in attrs:
149 if any(a in exclude_attributes for a in attrs): 149 ↛ 150line 149 didn't jump to line 150 because the condition on line 149 was never true
150 continue
151 yield attr