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