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 Unified 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


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








<
<








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.




# 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


# 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"]
     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.




## other modules

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









|





|
|
>
>








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 = ["pluginconf", "flit"]
     build-backend = "pluginconf.flit"

     [project]
     name = "projectname"

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

<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>
</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>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>








|




|








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=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>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

<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>
</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>








<
<
<
<
<
<
















|



















<














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.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 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.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

<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>
</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>
<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>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>








|



|


|
|
>
>








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>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 some shortcut parameters:</p>
<h2 id="parameters">Parameters</h2>
<dl>
<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






# 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"

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

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












>












|






>
>
>
>
>

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"

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