🐶🕵️ Scooby

一只转变成了Python环境侦探的Great Dane

这是一个轻量级工具，可以轻松报告您的Python环境中的包版本和硬件资源。

从PyPI安装

pip install scooby

或从conda-forge安装

conda install -c conda-forge scooby

Scooby为Jupyter笔记本提供HTML格式化，为几乎所有其他环境提供丰富的文本格式化。我们设计此模块以保持轻量级，以便在调试时将其轻松添加为Python项目的依赖项，以便报告环境。只需将scooby添加到依赖项中，并实现一个函数以让scooby报告您最关心的环境方面。

如果scooby无法检测到您想要了解的环境方面，请将此信息与我们分享，作为功能请求或拉取请求。

ScOOBY 报告是基于为 Dieter Werthmüller 创建的版本控制脚本，并为 empymod、emg3d 和 SimPEG 框架所编写的。它受到了来自 qutip 的 ipynbtools.py 和 watermark.py 的强烈启发。此软件包已修改以创建轻量级实现，使其可以轻松地作为任何 Python 库中的环境报告工具使用，并且对环境的影响最小。

用法

生成报告

报告以 html 表格的形式在 Jupyter 笔记本中渲染，如上截图所示，否则以纯文本列表形式呈现。如果您既没有在笔记本单元格的末尾输出 Report 对象，也没有在纯 Python 脚本中的某个地方生成它，那么您可能需要打印 Report 对象：print(scooby.Report())，但请注意，这只会输出脚本的纯文本表示。

>>> import scooby
>>> scooby.Report()

--------------------------------------------------------------------------------
  Date: Wed Feb 12 15:35:43 2020 W. Europe Standard Time

                OS : Windows
            CPU(s) : 16
           Machine : AMD64
      Architecture : 64bit
               RAM : 31.9 GiB
       Environment : IPython

  Python 3.7.6 | packaged by conda-forge | (default, Jan  7 2020, 21:48:41)
  [MSC v.1916 64 bit (AMD64)]

             numpy : 1.18.1
             scipy : 1.3.1
           IPython : 7.12.0
        matplotlib : 3.0.3
            scooby : 0.5.0

  Intel(R) Math Kernel Library Version 2019.0.4 Product Build 20190411 for
  Intel(R) 64 architecture applications
--------------------------------------------------------------------------------

对于所有的 Scooby-Doo 粉丝来说，doo 是 Report 的别名，因此您可以非常满足地做

>>> import scooby
>>> scooby.doo()

--------------------------------------------------------------------------------
  Date: Thu Nov 25 09:47:50 2021 MST

                OS : Darwin
            CPU(s) : 12
           Machine : x86_64
      Architecture : 64bit
               RAM : 32.0 GiB
       Environment : Python
       File system : apfs

  Python 3.8.12 | packaged by conda-forge | (default, Oct 12 2021, 21:50:38)
  [Clang 11.1.0 ]

             numpy : 1.21.4
             scipy : 1.7.3
           IPython : 7.29.0
        matplotlib : 3.5.0
            scooby : 0.5.8
--------------------------------------------------------------------------------

或者更好

from scooby import doo as doobiedoo

除了默认（可选）包之外，您还可以提供额外的包，可以是字符串或已导入的包

>>> import pyvista
>>> import scooby
>>> scooby.Report(additional=[pyvista, 'vtk', 'no_version', 'does_not_exist'])

--------------------------------------------------------------------------------
  Date: Wed Feb 12 16:15:15 2020 W. Europe Standard Time

                OS : Windows
            CPU(s) : 16
           Machine : AMD64
      Architecture : 64bit
               RAM : 31.9 GiB
       Environment : IPython

  Python 3.7.6 | packaged by conda-forge | (default, Jan  7 2020, 21:48:41)
  [MSC v.1916 64 bit (AMD64)]

           pyvista : 0.23.1
               vtk : 8.1.2
        no_version : Version unknown
    does_not_exist : Could not import
             numpy : 1.18.1
             scipy : 1.3.1
           IPython : 7.12.0
        matplotlib : 3.0.3
            scooby : 0.5.0

  Intel(R) Math Kernel Library Version 2019.0.4 Product Build 20190411 for
  Intel(R) 64 architecture applications
--------------------------------------------------------------------------------

此外，scooby 还会报告是否无法导入包或无法确定包的版本。

其他有用的参数包括

• ncol：html 表格中的列数；
• text_width：纯文本版本的文本宽度；
• sort：如果为 True，则按字母顺序对列表进行排序。

除了 additional 之外，还有两个列表，core 和 optional，可以用来提供包名。然而，它们主要用于希望使用 scooby 创建他们报告系统的包维护者（见下文）。

在项目中实现 scooby

您可以在项目中轻松使用 scooby 生成自定义的 Report 实例

class Report(scooby.Report):
    def __init__(self, additional=None, ncol=3, text_width=80, sort=False):
        """Initiate a scooby.Report instance."""

        # Mandatory packages.
        core = ['yourpackage', 'your_core_packages', 'e.g.', 'numpy', 'scooby']

        # Optional packages.
        optional = ['your_optional_packages', 'e.g.', 'matplotlib']

        scooby.Report.__init__(self, additional=additional, core=core,
                               optional=optional, ncol=ncol,
                               text_width=text_width, sort=sort)

这使得您的项目用户在提交错误时，可以快速生成有关所有相关包版本和环境详细信息的报告变得特别容易。

>>> import your_package
>>> your_package.Report()

core 列表中的包是您项目的必需包，而 optional 列表可以用于可选包。保持 additional 列表为空，以便用户可以向列表中添加包。

作为软依赖实现

如果您想实现 scooby，但又不愿意将另一个依赖项添加到您的包中，这里有一个简单的方法可以轻松地将 scooby 作为软依赖项使用。不要使用 import scooby，而是使用以下代码片段

# Make scooby a soft dependency:
try:
    from scooby import Report as ScoobyReport
except ImportError:
    class ScoobyReport:
        def __init__(self, *args, **kwargs):
            message = (
                '\n  *ERROR*: `Report` requires `scooby`.'
                '\n           Install it via `pip install scooby` or'
                '\n           `conda install -c conda-forge scooby`.\n'
            )
            raise ImportError(message)

然后创建与上面相同的自定义 Report 类

class Report(ScoobyReport):
    def __init__(self, additional=None, ncol=3, text_width=80, sort=False):
        """Initiate a scooby.Report instance."""

        # Mandatory packages.
        core = ['yourpackage', 'your_core_packages', 'e.g.', 'numpy', 'scooby']

        # Optional packages.
        optional = ['your_optional_packages', 'e.g.', 'matplotlib']

        scooby.Report.__init__(self, additional=additional, core=core,
                               optional=optional, ncol=ncol,
                               text_width=text_width, sort=sort)

如果用户已安装 scooby，则一切正常。如果没有安装 scooby，将引发以下异常

>>> import your_package
>>> your_package.Report()

  *ERROR*: `Report` requires `scooby`
           Install it via `pip install scooby` or
           `conda install -c conda-forge scooby`.

为任何包自动生成报告

Scooby 可以使用 AutoReport 类自动为任何包及其分发需求生成报告

>>> import scooby
>>> scooby.AutoReport('matplotlib')

--------------------------------------------------------------------------------
  Date: Fri Oct 20 16:49:34 2023 PDT

                OS : Darwin
            CPU(s) : 8
           Machine : arm64
      Architecture : 64bit
               RAM : 16.0 GiB
       Environment : Python
       File system : apfs

  Python 3.11.3 | packaged by conda-forge | (main, Apr  6 2023, 08:58:31)
  [Clang 14.0.6 ]

        matplotlib : 3.7.1
         contourpy : 1.0.7
            cycler : 0.11.0
         fonttools : 4.39.4
        kiwisolver : 1.4.4
             numpy : 1.24.3
         packaging : 23.1
            pillow : 9.5.0
         pyparsing : 3.0.9
   python-dateutil : 2.8.2
--------------------------------------------------------------------------------

解开谜团

您是否在 IPython、Jupyter 或普通 Python 中执行代码的谜团中挣扎？尝试使用 scooby 的一些调查功能来解决这些类型的谜团

import scooby

if scooby.in_ipykernel():
    # Do Jupyter/IPyKernel stuff
elif scooby.in_ipython():
    # Do IPython stuff
else:
    # Do normal, boring Python stuff

Scooby 如何获取版本号？

我们会检查几个位置，并在需要时很高兴地实现更多，只需打开一个问题！

目前，它看起来像以下位置

• __version__
• version
• 在 scooby 知识库中查找 VERSION_ATTRIBUTES
• 在 scooby 知识库中查找 VERSION_METHODS

VERSION_ATTRIBUTES 是一个字典，包含具有非标准位置的已知 Python 包的属性。您可以通过以下方式添加其他已知位置

scooby.knowledge.VERSION_ATTRIBUTES['a_module'] = 'Awesome_version_location'

类似地，VERSION_METHODS 是一个字典，用于检索版本的方法，您也可以同样添加您的方法，该方法将获取包的版本。

使用 scooby 获取版本信息。

如果您只对单个软件包的版本感兴趣，也可以使用scooby。以下是一些示例

>>> import scooby, numpy
>>> scooby.get_version(numpy)
('numpy', '1.16.4')
>>> scooby.get_version('no_version')
('no_version', 'Version unknown')
>>> scooby.get_version('does_not_exist')
('does_not_exist', 'Could not import')

注意，模块可以以已加载的形式或作为字符串提供。

在会话中跟踪导入

Scooby具有在Python会话期间跟踪所有导入模块的能力，这样会话中使用的任何导入的、非标准库包都会通过TrackedReport报告。例如，通过导入scooby并使用track_imports()函数启用跟踪来启动会话。然后，会话期间导入的所有后续软件包都将被跟踪，scooby可以报告它们的版本。一旦准备好生成Report，就实例化一个TrackedReport对象。

在以下示例中，我们导入了一个来自scipy的常量，这将报告scipy和numpy的版本，因为这两个软件包都在会话中加载（注意numpy是由scipy内部加载的）。

>>> import scooby
>>> scooby.track_imports()

>>> from scipy.constants import mu_0 # a float value

>>> scooby.TrackedReport()

--------------------------------------------------------------------------------
  Date: Thu Apr 16 15:33:11 2020 MDT

                OS : Linux
            CPU(s) : 8
           Machine : x86_64
      Architecture : 64bit
               RAM : 62.7 GiB
       Environment : IPython

  Python 3.7.7 (default, Mar 10 2020, 15:16:38)  [GCC 7.5.0]

            scooby : 0.5.2
             numpy : 1.18.1
             scipy : 1.4.1
--------------------------------------------------------------------------------

命令行界面

Scooby提供了一个命令行界面。只需在终端中输入

scooby

即可显示默认报告。您还可以使用CLI显示其他软件包的scooby报告，如果该软件包实现了上述建议的Report类，可以使用packagename.Report()。

例如，要打印pyvista的报告，可以运行

scooby -r pyvista

这将显示PyVista中实现的报告。

CLI还可以根据软件包的分发依赖关系生成报告，其中该软件包没有实现Report类。例如，我们可以为matplotlib及其依赖项生成报告

$ scooby -r matplotlib
--------------------------------------------------------------------------------
  Date: Fri Oct 20 17:03:45 2023 PDT

                 OS : Darwin
             CPU(s) : 8
            Machine : arm64
       Architecture : 64bit
                RAM : 16.0 GiB
        Environment : Python
        File system : apfs

  Python 3.11.3 | packaged by conda-forge | (main, Apr  6 2023, 08:58:31)
  [Clang 14.0.6 ]

         matplotlib : 3.7.1
          contourpy : 1.0.7
             cycler : 0.11.0
          fonttools : 4.39.4
         kiwisolver : 1.4.4
              numpy : 1.24.3
          packaging : 23.1
             pillow : 9.5.0
          pyparsing : 3.0.9
    python-dateutil : 2.8.2
importlib-resources : 5.12.0
--------------------------------------------------------------------------------

只需输入

scooby --help

即可查看所有可能性。

可选需求

以下是可选需求和它们的目的列表

• psutil：报告总RAM（GiB）
• mkl-services：报告Intel(R) Math Kernel Library版本