dissect.target 3.15.dev2__py3-none-any.whl → 3.15.dev4__py3-none-any.whl

dissect/target/plugin.py

@@ -292,18 +292,43 @@ class OSPlugin(Plugin):
     This provides a base class for certain common functions of OS's, which each OS plugin has to implement separately.
 
     For example, it provides an interface for retrieving the hostname and users of a target.
+
+    All derived classes MUST implement ALL the classmethods and exported
+    methods with the same ``@classmethod`` or ``@export(...)`` annotation.
     """
 
+    def __init_subclass__(cls, **kwargs):
+        # Note that cls is the subclass
+        super().__init_subclass__(**kwargs)
+
+        for os_method in get_nonprivate_attributes(OSPlugin):
+            if isinstance(os_method, property):
+                os_method = os_method.fget
+            os_docstring = os_method.__doc__
+
+            method = getattr(cls, os_method.__name__, None)
+            if isinstance(method, property):
+                method = method.fget
+            # This works as None has a __doc__ property (which is None).
+            docstring = method.__doc__
+
+            if method and not docstring:
+                if hasattr(method, "__func__"):
+                    method = method.__func__
+                method.__doc__ = os_docstring
+
     def check_compatible(self) -> bool:
-        """OSPlugin's use a different compatibility check, override the default one."""
+        """OSPlugin's use a different compatibility check, override the one from the :class:`Plugin` class.
+
+        Returns:
+            This function always returns ``True``.
+        """
         return True
 
     @classmethod
     def detect(cls, fs: Filesystem) -> Optional[Filesystem]:
         """Provide detection of this OSPlugin on a given filesystem.
 
-        Note: must be implemented as a classmethod.
-
         Args:
             fs: :class:`~dissect.target.filesystem.Filesystem` to detect the OS on.
 
@@ -316,11 +341,9 @@ class OSPlugin(Plugin):
     def create(cls, target: Target, sysvol: Filesystem) -> OSPlugin:
         """Initiate this OSPlugin with the given target and detected filesystem.
 
-        Note: must be implemented as a classmethod.
-
         Args:
-            target: The Target object.
-            sysvol: The filesystem that was detected in the detect() function.
+            target: The :class:`~dissect.target.target.Target` object.
+            sysvol: The filesystem that was detected in the ``detect()`` function.
 
         Returns:
             An instantiated version of the OSPlugin.
@@ -329,9 +352,7 @@ class OSPlugin(Plugin):
 
     @export(property=True)
     def hostname(self) -> Optional[str]:
-        """Required OS function.
-
-        Implementations must be decorated with ``@export(property=True)``.
+        """Return the target's hostname.
 
         Returns:
             The hostname as string.
@@ -340,9 +361,7 @@ class OSPlugin(Plugin):
 
     @export(property=True)
     def ips(self) -> list[str]:
-        """Required OS function.
-
-        Implementations must be decorated with ``@export(property=True)``.
+        """Return the IP addresses configured in the target.
 
         Returns:
             The IPs as list.
@@ -351,9 +370,7 @@ class OSPlugin(Plugin):
 
     @export(property=True)
     def version(self) -> Optional[str]:
-        """Required OS function.
-
-        Implementations must be decorated with ``@export(property=True)``.
+        """Return the target's OS version.
 
         Returns:
             The OS version as string.
@@ -362,9 +379,7 @@ class OSPlugin(Plugin):
 
     @export(record=EmptyRecord)
     def users(self) -> list[Record]:
-        """Required OS function.
-
-        Implementations must be decorated with @export.
+        """Return the users available in the target.
 
         Returns:
             A list of user records.
@@ -373,9 +388,7 @@ class OSPlugin(Plugin):
 
     @export(property=True)
     def os(self) -> str:
-        """Required OS function.
-
-        Implementations must be decorated with ``@export(property=True)``.
+        """Return a slug of the target's OS name.
 
         Returns:
             A slug of the OS name, e.g. 'windows' or 'linux'.
@@ -384,9 +397,7 @@ class OSPlugin(Plugin):
 
     @export(property=True)
     def architecture(self) -> Optional[str]:
-        """Required OS function.
-
-        Implementations must be decorated with ``@export(property=True)``.
+        """Return a slug of the target's OS architecture.
 
         Returns:
             A slug of the OS architecture, e.g. 'x86_32-unix', 'MIPS-linux' or
@@ -1128,29 +1139,45 @@ def find_plugin_functions(
     ignore_load_errors = kwargs.get("ignore_load_errors", False)
 
     for pattern in patterns.split(","):
-        # backward compatibility fix for namespace-level plugins (i.e. chrome)
+        # Backward compatibility fix for namespace-level plugins (i.e. chrome)
+        # If an exact namespace match is found, the pattern is changed to the tree to that namespace.
+        # Examples:
+        #     -f browser -> apps.browser.browser
+        #     -f iexplore -> apps.browser.iexplore
+        namespace_match = False
         for index_name, func in functions.items():
             if func["namespace"] == pattern:
-                pattern = func["module"] + "*"
+                pattern = func["module"]
+                namespace_match = True
+                break
 
         wildcard = any(char in pattern for char in ["*", "!", "?", "[", "]"])
         treematch = pattern.split(".")[0] in rootset and pattern != "os"
         exact_match = pattern in functions
 
-        # Allow for exact matches, otherwise you cannot reach documented namespace plugins like
-        # browsers.browser.downloads. You can *always* run these using the namespace/classic-style like:
-        # browser.downloads (but -l lists them in the tree for documentation purposes so it would be misleading
-        # not to allow tree access as well). Note that these tree items will never respond to wildcards though
-        # (browsers.browser.* won't work) to avoid duplicate results.
-        if exact_match:
+        # Allow for exact and namespace matches even if the plugin does not want to be found, otherwise you cannot
+        # reach documented namespace plugins like apps.browser.browser.downloads.
+        # You can *always* run these using the namespace/classic-style like: browser.downloads (but -l lists them
+        # in the tree for documentation purposes so it would be misleading not to allow tree access as well).
+        #
+        # Note that these tree items will never respond to wildcards though to avoid duplicate results, e.g. when
+        # querying apps.browser.*, this also means apps.browser.browser.* won't work.
+        if exact_match or namespace_match:
             show_hidden = True
 
-        if treematch and not wildcard and not exact_match:
-            # Examples:
-            #     -f browsers -> browsers* (the whole package)
-            #     -f apps.webservers.iis -> apps.webservers.iis* (logs etc)
-            # We do not include  a dot because that does not work if the full path is given:
-            #     -f apps.webservers.iis.logs != apps.webservers.iis.logs.* (does not work)
+        # Change the treematch pattern into an fnmatch-able pattern to give back all functions from the sub-tree
+        # (if there is a subtree).
+        #
+        # Examples:
+        #     -f browser -> apps.browser.browser* (the whole package, due to a namespace match)
+        #     -f apps.webservers.iis -> apps.webservers.iis* (logs etc)
+        #     -f apps.webservers.iis.logs -> apps.webservers.iis.logs* (only the logs, there is no subtree)
+        # We do not include a dot because that does not work if the full path is given:
+        #     -f apps.webservers.iis.logs != apps.webservers.iis.logs.* (does not work)
+        #
+        # In practice a namespace_match would almost always also be a treematch, except when the namespace plugin
+        # is in the root of the plugin tree.
+        if (treematch or namespace_match) and not wildcard and not exact_match:
             pattern += "*"
 
         if wildcard or treematch:

{dissect.target-3.15.dev2.dist-info → dissect.target-3.15.dev4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: dissect.target
-Version: 3.15.dev2
+Version: 3.15.dev4
 Summary: This module ties all other Dissect modules together, it provides a programming API and command line tools which allow easy access to various data sources inside disk images or file collections (a.k.a. targets)
 Author-email: Dissect Team <dissect@fox-it.com>
 License: Affero General Public License v3

{dissect.target-3.15.dev2.dist-info → dissect.target-3.15.dev4.dist-info}/RECORD

@@ -3,7 +3,7 @@ dissect/target/container.py,sha256=9ixufT1_0WhraqttBWwQjG80caToJqvCX8VjFk8d5F0,9
 dissect/target/exceptions.py,sha256=VVW_Rq_vQinapz-2mbJ3UkxBEZpb2pE_7JlhMukdtrY,2877
 dissect/target/filesystem.py,sha256=oCPNw09I3odf69HKkqph6EM5-AywAQIn9UPO-BxtbpY,53445
 dissect/target/loader.py,sha256=4ZdX-QJY83NPswTyNG31LUwYXdV1tuByrR2vKKg7d5k,7214
-dissect/target/plugin.py,sha256=F-VHirvGu0iX2-TOJWx-THzzhfo712oiARt7zXOzWqE,45855
+dissect/target/plugin.py,sha256=MyBjC7uJ-qml9SQMQ6xsNMdudsOFNJiHNMRn-AFi_pM,47405
 dissect/target/report.py,sha256=06uiP4MbNI8cWMVrC1SasNS-Yg6ptjVjckwj8Yhe0Js,7958
 dissect/target/target.py,sha256=CuqLTD3fwr4HIxtDgN_fwJ3UHSqe5PhNJlLTVGsluB8,31908
 dissect/target/volume.py,sha256=aQZAJiny8jjwkc9UtwIRwy7nINXjCxwpO-_UDfh6-BA,15801
@@ -305,10 +305,10 @@ dissect/target/volumes/luks.py,sha256=v_mHW05KM5iG8JDe47i2V4Q9O0r4rnAMA9m_qc9cYw
 dissect/target/volumes/lvm.py,sha256=wwQVR9I3G9YzmY6UxFsH2Y4MXGBcKL9aayWGCDTiWMU,2269
 dissect/target/volumes/md.py,sha256=j1K1iKmspl0C_OJFc7-Q1BMWN2OCC5EVANIgVlJ_fIE,1673
 dissect/target/volumes/vmfs.py,sha256=-LoUbn9WNwTtLi_4K34uV_-wDw2W5hgaqxZNj4UmqAQ,1730
-dissect.target-3.15.dev2.dist-info/COPYRIGHT,sha256=m-9ih2RVhMiXHI2bf_oNSSgHgkeIvaYRVfKTwFbnJPA,301
-dissect.target-3.15.dev2.dist-info/LICENSE,sha256=DZak_2itbUtvHzD3E7GNUYSRK6jdOJ-GqncQ2weavLA,34523
-dissect.target-3.15.dev2.dist-info/METADATA,sha256=XCTfv2LwZTgA3EKVzxMYwgeOCdSa6vHIRGCGut_SRBE,11106
-dissect.target-3.15.dev2.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
-dissect.target-3.15.dev2.dist-info/entry_points.txt,sha256=tvFPa-Ap-gakjaPwRc6Fl6mxHzxEZ_arAVU-IUYeo_s,447
-dissect.target-3.15.dev2.dist-info/top_level.txt,sha256=Mn-CQzEYsAbkxrUI0TnplHuXnGVKzxpDw_po_sXpvv4,8
-dissect.target-3.15.dev2.dist-info/RECORD,,
+dissect.target-3.15.dev4.dist-info/COPYRIGHT,sha256=m-9ih2RVhMiXHI2bf_oNSSgHgkeIvaYRVfKTwFbnJPA,301
+dissect.target-3.15.dev4.dist-info/LICENSE,sha256=DZak_2itbUtvHzD3E7GNUYSRK6jdOJ-GqncQ2weavLA,34523
+dissect.target-3.15.dev4.dist-info/METADATA,sha256=ZHcCCAily7wTHdfI01lHfl1RXkpa00HXb_oUyZUtO3M,11106
+dissect.target-3.15.dev4.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
+dissect.target-3.15.dev4.dist-info/entry_points.txt,sha256=tvFPa-Ap-gakjaPwRc6Fl6mxHzxEZ_arAVU-IUYeo_s,447
+dissect.target-3.15.dev4.dist-info/top_level.txt,sha256=Mn-CQzEYsAbkxrUI0TnplHuXnGVKzxpDw_po_sXpvv4,8
+dissect.target-3.15.dev4.dist-info/RECORD,,