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