From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: <pve-devel-bounces@lists.proxmox.com> Received: from firstgate.proxmox.com (firstgate.proxmox.com [IPv6:2a01:7e0:0:424::9]) by lore.proxmox.com (Postfix) with ESMTPS id 23FC51FF15C for <inbox@lore.proxmox.com>; Wed, 26 Mar 2025 15:21:11 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 2E8A139136; Wed, 26 Mar 2025 15:21:04 +0100 (CET) From: Max Carrara <m.carrara@proxmox.com> To: pve-devel@lists.proxmox.com Date: Wed, 26 Mar 2025 15:20:51 +0100 Message-Id: <20250326142059.261938-1-m.carrara@proxmox.com> X-Mailer: git-send-email 2.39.5 MIME-Version: 1.0 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.075 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment RCVD_IN_VALIDITY_CERTIFIED_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to Validity was blocked. See https://knowledge.validity.com/hc/en-us/articles/20961730681243 for more information. RCVD_IN_VALIDITY_RPBL_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to Validity was blocked. See https://knowledge.validity.com/hc/en-us/articles/20961730681243 for more information. RCVD_IN_VALIDITY_SAFE_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to Validity was blocked. See https://knowledge.validity.com/hc/en-us/articles/20961730681243 for more information. SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record URIBL_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to URIBL was blocked. See http://wiki.apache.org/spamassassin/DnsBlocklists#dnsbl-block for more information. [plugin.pm, proxmox.com, pluginbase.pm] Subject: [pve-devel] [PATCH v1 pve-storage 0/8] Base Module + Documentation for PVE::Storage::Plugin API X-BeenThere: pve-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox VE development discussion <pve-devel.lists.proxmox.com> List-Unsubscribe: <https://lists.proxmox.com/cgi-bin/mailman/options/pve-devel>, <mailto:pve-devel-request@lists.proxmox.com?subject=unsubscribe> List-Archive: <http://lists.proxmox.com/pipermail/pve-devel/> List-Post: <mailto:pve-devel@lists.proxmox.com> List-Help: <mailto:pve-devel-request@lists.proxmox.com?subject=help> List-Subscribe: <https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel>, <mailto:pve-devel-request@lists.proxmox.com?subject=subscribe> Reply-To: Proxmox VE development discussion <pve-devel@lists.proxmox.com> Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: pve-devel-bounces@lists.proxmox.com Sender: "pve-devel" <pve-devel-bounces@lists.proxmox.com> Abstract Base Module + Documentation for PVE::Storage::Plugin API - v1 ====================================================================== This series adds a base module (interface) for PVE::Storage::Plugin, named PVE::Storage::PluginBase, which lists all methods that are part of the Storage Plugin API. Additionally, docstrings for every method are added in order to provide context for (third-party) developers, as sometimes a complete roundtrip through our code is otherwise necessary in order to (really) understand what a method does. Special thanks go to @Maximilano, who has helped me out a lot with this series! Essentially, the base module is similar to PVE::LXC::Plugin [1], with the exception that docstrings are added. Instead of documenting every single parameter separately, common / recurring method parameters are listed and explained at the very top of the file. The caching mechanism of a few methods is also described in the top-level documentation. Any feedback regarding the docs is highly appreciated -- I hope that we haven't overlooked anything. We tried to keep things concise unless it's absolutely necessary to add additional context. Also, most (but not all) of the methods `croak` right now if they're unimplemented, but I feel like default return values for certain methods could be returned instead. Then again, ::Plugin already provides those defaults, so I'm not sure if it matters either way. References ---------- [1]: https://git.proxmox.com/?p=pve-container.git;a=blob;f=src/PVE/LXC/Setup/Plugin.pm;h=b9d9c2d9d19e086438faeda6cfce8f854dddc7ea;hb=refs/heads/master Summary of Changes ------------------ Max Carrara (8): pluginbase: introduce PVE::Storage::PluginBase with doc scaffold pluginbase: add high-level plugin API description pluginbase: document SectionConfig methods pluginbase: document general plugin methods pluginbase: document hooks pluginbase: document image operation methods pluginbase: document volume operations pluginbase: document import and export methods src/PVE/Storage/Makefile | 1 + src/PVE/Storage/Plugin.pm | 2 +- src/PVE/Storage/PluginBase.pm | 1475 +++++++++++++++++++++++++++++++++ 3 files changed, 1477 insertions(+), 1 deletion(-) create mode 100644 src/PVE/Storage/PluginBase.pm -- 2.39.5 _______________________________________________ pve-devel mailing list pve-devel@lists.proxmox.com https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel