Coverage for src/debputy/plugin/api/std_docs.py: 84%
16 statements
« prev ^ index » next coverage.py v7.6.0, created at 2025-01-27 13:59 +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.plugin.debputy.to_be_api_types import (
11 OptionalInstallDirectly,
12 OptionalInSourceBuild,
13 OptionalBuildDirectory,
14 BuildRuleParsedFormat,
15)
17_STD_ATTR_DOCS: Mapping[
18 Type[DebputyParsedContent],
19 Sequence[ParserAttributeDocumentation],
20] = {
21 BuildRuleParsedFormat: [
22 StandardParserAttributeDocumentation(
23 frozenset(["name"]),
24 textwrap.dedent(
25 """\
26 The name of the build step.
28 The name is used for multiple things, such as:
29 1) If you ever need to reference the build elsewhere, the name will be used.
30 2) When `debputy` references the build in log output and error, it will use the name.
31 3) It is used as defaults for when `debputy` derives build and `DESTDIR` directories
32 for the build.
33 """
34 ),
35 # Put in top,
36 sort_category=-1000,
37 ),
38 StandardParserAttributeDocumentation(
39 frozenset(["for_packages"]),
40 textwrap.dedent(
41 """\
42 Which package or packages this build step applies to.
44 Either a package name or a list of package names.
45 """
46 ),
47 ),
48 StandardParserAttributeDocumentation(
49 frozenset(["environment"]),
50 textwrap.dedent(
51 """\
52 Specify that this build step uses the named environment
54 If omitted, the default environment will be used. If no default environment is present,
55 then this option is mandatory.
56 """
57 ),
58 ),
59 ],
60 OptionalBuildDirectory: [
61 StandardParserAttributeDocumentation(
62 frozenset(["build_directory"]),
63 textwrap.dedent(
64 """\
65 The build directory to use for the build.
67 By default, `debputy` will derive a build directory automatically if the build system needs
68 it. However, it can be useful if you need to reference the directory name from other parts
69 of the manifest or want a "better" name than `debputy` comes up with.
70 """
71 ),
72 ),
73 ],
74 OptionalInSourceBuild: [
75 StandardParserAttributeDocumentation(
76 frozenset(["perform_in_source_build"]),
77 textwrap.dedent(
78 """\
79 Whether the build system should use "in source" or "out of source" build.
81 This is mostly useful for forcing "in source" builds for build systems that default to
82 "out of source" builds like `autoconf`.
84 The default depends on the build system and the value of the `build-directory` attribute
85 (if supported by the build system).
86 """
87 ),
88 # Late
89 sort_category=500,
90 ),
91 ],
92 OptionalInstallDirectly: [
93 StandardParserAttributeDocumentation(
94 frozenset(["install_directly_to_package"]),
95 textwrap.dedent(
96 """\
97 Whether the build system should install all upstream content directly into the package.
99 This option is mostly useful for disabling said behavior by setting the attribute to `false`.
100 The attribute conditionally defaults to `true` when the build only applies to one package.
101 If explicitly set to `true`, then this build step must apply to exactly one package (usually
102 implying that `for` is set to that package when the source builds multiple packages).
104 When `true`, this behaves similar to `dh_auto_install --destdir=debian/PACKAGE`.
105 """
106 ),
107 ),
108 ],
109 DebputyParsedContentStandardConditional: [
110 StandardParserAttributeDocumentation(
111 frozenset(["when"]),
112 textwrap.dedent(
113 """\
114 A condition as defined in [Conditional rules](${MANIFEST_FORMAT_DOC}#conditional-rules).
116 The conditional will disable the entire rule when the conditional evaluates to false.
117 """
118 ),
119 # Last
120 sort_category=9999,
121 ),
122 ],
123}
126def docs_from(
127 *ts: Any,
128 exclude_attributes: Container[str] = frozenset(),
129) -> Iterable[ParserAttributeDocumentation]:
130 """Provide standard attribute documentation from existing types
132 This is a work-around for `apply_standard_attribute_documentation` requiring python3.12.
133 If you can assume python3.12, use `apply_standard_attribute_documentation` instead.
134 """
135 for t in ts:
136 attrs = _STD_ATTR_DOCS.get(t)
137 if attrs is None: 137 ↛ 138line 137 didn't jump to line 138 because the condition on line 137 was never true
138 raise ValueError(f"No standard documentation for {str(t)}")
139 for attr in attrs:
140 if any(a in exclude_attributes for a in attrs): 140 ↛ 141line 140 didn't jump to line 141 because the condition on line 140 was never true
141 continue
142 yield attr