Overview
Comment:update docs
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 3f778d96b79453c9184973186cf2e7cee3e1f477a9cf8861f64ef2cc52c58088
User & Date: mario on 2022-10-28 07:14:51
Other Links: manifest | tags
Context
2022-10-28
07:46
remove test value check-in: 3fa8451133 user: mario tags: trunk
07:14
update docs check-in: 3f778d96b7 user: mario tags: trunk
07:11
update commentary, force dynamic= fields, skip field if set via ini, adapt to .setup changes check-in: ff3080056a user: mario tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Modified README.md from [05362db7a2] to [4aec538275].

︙
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

39
40
41
42
43
44
45


46
47
48
49
50
51
52








-
-









What for then?

>  * Separates code from meta data. Avoids keeping seldomly used descriptors in variables.
>  * Does away with externalized ini/json files for modules, yet simplifies use of external tooling.
>  * Minimizes premature module loading just to inspect meta information.

pluginconf is foremost about the universal meta comment format.


# API

Lookup configuration is currently just done through injection:

    plugin_base = [__package__, "myapp.plugins", "/usr/share/app/extensions"]
    module_base = "pluginconf"  # or any top-level app module
︙
173
174
175
176
177
178
179
180

181
182
183
184
185
186
187




188
189
190
191
192
193
194

171
172
173
174
175
176
177

178
179
180
181
182
183


184
185
186
187
188
189
190
191
192
193
194








-
+





-
-
+
+
+
+









# flit wrapper

Alternatively, there's `pluginconf.flit` to utilize pyproject.toml for
building packages, while sourcing meta data from the primary package file.

     [build-system]
     requires = ["flit_core", "pluginconf"]
     requires = ["pluginconf", "flit"]
     build-backend = "pluginconf.flit"

     [project]
     name = "projectname"

It can be invoked via `python -m pluginconf.flit build` or even
`flit-pluginconf build`. Field mapping isn't very robust yet.
It can be invoked via `flit-pluginconf build` /  `python -m pluginconf.flit build`
or even `python -m build`. Field mapping isn't very robust yet, and mercilessly
flaunts the `dynamic=` directive.



## other modules

 * `pluginconf.depends` provides `Check` for .valid() and .depends() probing
 * argparse_map() might also end up in a separate module.
︙

Modified html/depends.html from [c59d901773] to [fc174a2044].

︙
31
32
33
34
35
36
37
38

39
40
41
42
43

44
45
46
47
48
49
50

31
32
33
34
35
36
37

38
39
40
41
42

43
44
45
46
47
48
49
50








-
+




-
+








<section>
</section>
<section>
<h2 class="section-title" id="header-classes">Classes</h2>
<dl>
<dt id="pluginconf.depends.Check"><code class="flex name class">
<span>class <span class="ident">Check</span></span>
<span>(</span><span>add={}, core=['st2', 'uikit', 'config', 'action'])</span>
<span>(</span><span>add=None, core=['st2', 'uikit', 'config', 'action'])</span>
</code></dt>
<dd>
<div class="desc"><p>Now this definitely requires customization. Each plugin can carry
a list of (soft-) dependency names.</p>
<p># depends: config, appcore &gt;= 2.0, bin:wkhtmltoimage, python &lt; 3.5</p>
<p>… # depends: config, appcore &gt;= 2.0, bin:wkhtmltoimage, python &lt; 3.5</p>
<p>Here only in-application modules are honored, system references
ignored. Unknown plugin names are also skipped. A real install
helper might want to auto-tick them on, etc. This example is just
meant for probing downloadable plugins.</p>
<p>The .valid() helper only asserts the api: string, or skips existing
modules, and if they're more recent.
While .depends() compares minimum versions against existing modules.</p>
︙

Modified html/flit.html from [5f3e858fb2] to [b481f5e446].

︙
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

27
28
29
30
31
32
33






34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

70
71
72
73
74
75
76
77
78
79
80
81
82








-
-
-
-
-
-
















-
+



















-














<section>
</section>
<section>
</section>
<section>
<h2 class="section-title" id="header-functions">Functions</h2>
<dl>
<dt id="pluginconf.flit.inject"><code class="name flex">
<span>def <span class="ident">inject</span></span>(<span>where)</span>
</code></dt>
<dd>
<div class="desc"><p>monkeypatch into module</p></div>
</dd>
<dt id="pluginconf.flit.make_metadata"><code class="name flex">
<span>def <span class="ident">make_metadata</span></span>(<span>module, ini_info)</span>
</code></dt>
<dd>
<div class="desc"><p>@inject different sourcing order to apply plugin meta fields</p></div>
</dd>
<dt id="pluginconf.flit.pmd_meta"><code class="name flex">
<span>def <span class="ident">pmd_meta</span></span>(<span>pmd, ini)</span>
</code></dt>
<dd>
<div class="desc"><p>enjoin PMD fields with flit.common.MetaData</p></div>
</dd>
<dt id="pluginconf.flit.read_flit_config"><code class="name flex">
<span>def <span class="ident">read_flit_config</span></span>(<span>path)</span>
</code></dt>
<dd>
<div class="desc"><p>@inject read_flit_config() with forced dynamic fields</p></div>
<div class="desc"><p>@inject patch_flit_config() with forced dynamic fields</p></div>
</dd>
</dl>
</section>
<section>
</section>
</article>
<nav id="sidebar">
<h1>Index</h1>
<div class="toc">
<ul></ul>
</div>
<ul id="index">
<li><h3>Super-module</h3>
<ul>
<li><code><a title="pluginconf" href="index.html">pluginconf</a></code></li>
</ul>
</li>
<li><h3><a href="#header-functions">Functions</a></h3>
<ul class="">
<li><code><a title="pluginconf.flit.inject" href="#pluginconf.flit.inject">inject</a></code></li>
<li><code><a title="pluginconf.flit.make_metadata" href="#pluginconf.flit.make_metadata">make_metadata</a></code></li>
<li><code><a title="pluginconf.flit.pmd_meta" href="#pluginconf.flit.pmd_meta">pmd_meta</a></code></li>
<li><code><a title="pluginconf.flit.read_flit_config" href="#pluginconf.flit.read_flit_config">read_flit_config</a></code></li>
</ul>
</li>
</ul>
</nav>
</main>
<footer id="footer">
<p>Generated by <a href="https://pdoc3.github.io/pdoc" title="pdoc: Python API documentation generator"><cite>pdoc</cite> 0.10.0</a>.</p>
</footer>
</body>
</html>

Modified html/setup.html from [e58aa12886] to [70f7b7c594].

︙
40
41
42
43
44
45
46
47

48
49
50
51

52
53
54
55




56
57
58
59
60
61
62

40
41
42
43
44
45
46

47
48
49
50

51
52
53


54
55
56
57
58
59
60
61
62
63
64








-
+



-
+


-
-
+
+
+
+








<dt id="pluginconf.setup.name_to_fn"><code class="name flex">
<span>def <span class="ident">name_to_fn</span></span>(<span>name)</span>
</code></dt>
<dd>
<div class="desc"><p>find primary entry point.py from package name</p></div>
</dd>
<dt id="pluginconf.setup.setup"><code class="name flex">
<span>def <span class="ident">setup</span></span>(<span>debug=0, **kwargs)</span>
<span>def <span class="ident">setup</span></span>(<span>filename=None, debug=False, **kwargs)</span>
</code></dt>
<dd>
<div class="desc"><p>Wrapper around <code>setuptools.setup()</code> which adds some defaults
and plugin meta data import, with two shortcut params:</p>
and plugin meta data import, with some shortcut parameters:</p>
<h2 id="parameters">Parameters</h2>
<dl>
<dt><strong><code>fn</code></strong> :&ensp;<code>str</code></dt>
<dd>main file "pkg/main.py"</dd>
<dt><strong><code>filename</code></strong> :&ensp;<code>str</code></dt>
<dd>main file "pkg/main.py" (else deduced from primary package name)</dd>
<dt><strong><code>debug</code></strong> :&ensp;<code>bool</code></dt>
<dd>display collected options prior setuptools.setup() invocation</dd>
<dt><strong><code>long_description</code></strong> :&ensp;<code>str</code></dt>
<dd>e.g. "README.md", else comment block used</dd>
</dl>
<p>Other setup() params work as usual, and are passed trough. Notably
entry_points= or data_files= can be used, even if they get augmented.</p></div>
</dd>
</dl>
︙

Modified test/basic.py from [10b052f131] to [4798865c44]. 

1
2
3
4
5
6

7
8
9
10
11
12
13
14
15
16
17
18
19

20
21
22
23
24
25






1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

20
21
22
23
24
25
26
27
28
29
30
31







+












-
+






+
+
+
+
+

# type: test
# title: basic PMD
# description: check for some fields
# version: 0.1-rc1
# 
# This the doc.


import pytest
import pluginconf

@pytest.fixture
def pmd():
    return pluginconf.plugin_meta(fn=__file__)

def type_(pmd):
    assert pmd["type"] == "test"

def version_(pmd):
    assert pmd["version"] == "0.1-rc1"
    assert pmd.version == "0.1-rc1"

def title_(pmd):
    assert pmd["title"] == "basic PMD"

def doc_(pmd):
    assert pmd["doc"] == "This the doc."

# Should probably migrate all to pmd.property access now that we have PluginMeta wrapper
def test_all_as_props(pmd):
    for key, val in pmd.items():
        assert getattr(pmd, key) == val