| 修订版 | 3b89485a63592a2d6f5baaa1170c00816b65eca3 (tree) |
|---|---|
| 时间 | 2024-02-19 00:06:35 |
| 作者 | Albert Mietus < albert AT mietus DOT nl > |
| Commiter | Albert Mietus < albert AT mietus DOT nl > |
The summary of the (py,compiler) package structure is more-or-less done (DOC-only)
| @@ -26,23 +26,46 @@ | ||
| 26 | 26 | For those, that are not interested in de design-study, this is the result |
| 27 | 27 | |
| 28 | 28 | * The top-level namespace is ‘castle’, for all public, more-or-less official packages |
| 29 | - * Only base packages (which can’t be a plugin) are located directly in ‘castle’ | |
| 30 | - |BR| | |
| 31 | - This is mainly the common intermediate langage (``castle.aigr``), and the code to load the plugins and put them in | |
| 32 | - the pipeline (``castle.monorail``). Also some generic “main/app” routines can be located there. | |
| 29 | + * Only base packages (which can’t be a plugin) are located directly in ‘castle’. Also some generic “main/app” routines can be located there. | |
| 30 | + | |
| 31 | + - ``castle.aigr``, the common intermediate langage | |
| 32 | + - ``castle.monorail``, the code to load the plugins and put them in the pipeline | |
| 33 | + | |
| 33 | 34 | * Most packages are plugins and use a namespace that denotes the “location” in the pipeline; in plural form to |
| 34 | 35 | denotes the are options. |
| 35 | - |BR| | |
| 36 | - ``castle.readers.<name>``, ``castle.transformers.<name>``, ``castle.writers.<name>`` (not *backends*, as only the | |
| 37 | - writer-part is part of Castle.) | |
| 36 | + | |
| 37 | + - ``castle.readers.<name>`` | |
| 38 | + - ``castle.transformers.<name>`` | |
| 39 | + - ``castle.writers.<name>`` (not *backends*, as only the writer-part is part of Castle.) | |
| 40 | + | |
| 38 | 41 | * Use “pep 420” *native namespace packages* for all plugins. |
| 39 | - |BR| | |
| 40 | - In short: do never put an `__init__.py` file in the shared namespaces -- Only the “main” packages is allowed to put | |
| 41 | - files there. | |
| 42 | - * Optional, auxiliary (plugin) packages are usually named (placed-in) ``castle.<loc>.plugins.<opt>``. | |
| 42 | + | |
| 43 | + - *In short*: plugins should **never** put an `__init__.py` file in a *shared* namespace-part (like castle.readers.) | |
| 44 | + - Only the “main” package is allowed to put files there. | |
| 45 | + | |
| 46 | + * Optional, auxiliary (plugin) packages are usually named (placed-in) | |
| 47 | + | |
| 48 | + - ``castle.<loc>.plugins.<opt>``. | |
| 49 | + | |
| 43 | 50 | * Local (non public) extensions should normally *not* be in ‘castle’. |
| 51 | + * Optional plugins, that can be shared by many plugins for test, debug & development purposed are allowed in one | |
| 52 | + place in the castle-hierarchy, | |
| 44 | 53 | |
| 45 | -Before we describe the design, let study the options, our needs and how others handle this. | |
| 54 | + - ``castle.TESTDOUBLES.<hier>``, | |
| 55 | + | |
| 56 | + - *TESTDOUBLES* is in capitals, to signal it’s a specical case | |
| 57 | + - Those plugins should *not* have production code -- no application should depend/need those | |
| 58 | + |BR| (But for test & verification) | |
| 59 | + - *‘<hier>’* is typical namespace, below castle, like: aigr | |
| 60 | + | |
| 61 | + - ``castle.TESTDOUBLES.aigr.sieve`` holds (parts of) ‘:ref:`Castle-TheSieve`’ in ‘:ref:`AIGR`’, As test-input for | |
| 62 | + e.g. plugins. Or as reference for a reader. | |
| 63 | + | |
| 64 | + | |
| 65 | +Opportunity | |
| 66 | +=========== | |
| 67 | +Let study the options, our needs and how others handle packages & plugins, before designing for castle. | |
| 68 | + | |
| 46 | 69 | |
| 47 | 70 | Importing |
| 48 | 71 | --------- |
Fork
CCastle/DocParts/Design/01.Architecture/02.packages.rst