0
# Scooby
1

2
Scooby is a Python environment detective tool that provides comprehensive environment reporting capabilities. It easily reports Python environment package versions and hardware resources, making it ideal for debugging, environment documentation, and issue reproduction.
3

4
## Package Information
5

6
- **Package Name**: scooby
7
- **Language**: Python
8
- **Installation**: `pip install scooby`
9
- **Python Requirement**: >=3.8
10
- **Optional Extras**: `pip install scooby[cpu]` (for psutil and mkl support)
11

12
## Core Imports
13

14
```python
15
import scooby
16
```
17

18
For specific functionality:
19

20
```python
21
from scooby import Report, AutoReport, TrackedReport
22
from scooby import get_version, track_imports, untrack_imports
23
from scooby import in_ipython, in_ipykernel, get_standard_lib_modules
24
from scooby import meets_version, version_tuple, doo
25

26
# Constants from scooby.report module
27
from scooby.report import MODULE_NOT_FOUND, MODULE_TROUBLE, VERSION_NOT_FOUND
28
from scooby.report import get_distribution_dependencies
29
```
30

31
## Basic Usage
32

33
```python
34
import scooby
35

36
# Generate a basic environment report
37
report = scooby.Report()
38
print(report)
39

40
# Generate a report with additional packages
41
report = scooby.Report(additional=['numpy', 'pandas', 'matplotlib'])
42
print(report)
43

44
# Generate an HTML report (for Jupyter notebooks)
45
report = scooby.Report()
46
report._repr_html_()  # Returns HTML string
47

48
# Auto-generate report for a specific package and its dependencies
49
auto_report = scooby.AutoReport('numpy')
50
print(auto_report)
51

52
# Get version of a specific package
53
name, version = scooby.get_version('numpy')
54
print(f"{name}: {version}")
55
```
56

57
## Architecture
58

59
Scooby is organized around three main reporting strategies:
60

61
- **Report**: Manual specification of packages to include in environment reports
62
- **AutoReport**: Automatic detection of package dependencies from distribution metadata
63
- **TrackedReport**: Dynamic tracking of imports during a Python session
64

65
The reporting system collects both system information (OS, CPU, RAM) and package versions through multiple detection mechanisms to handle various package installation and versioning patterns.
66

67
## Capabilities
68

69
### Environment Reporting
70

71
Create comprehensive environment reports showing system information, Python version, and package versions. Supports both plain text and HTML output formats for different environments.
72

73
```python { .api }
74
class Report:
75
    def __init__(
76
        self,
77
        additional=None,
78
        core=None,
79
        optional=None,
80
        ncol=4,
81
        text_width=80,
82
        sort=False,
83
        extra_meta=None,
84
        max_width=None
85
    ): ...
86

87
class AutoReport(Report):
88
    def __init__(
89
        self,
90
        module,
91
        additional=None,
92
        ncol=3,
93
        text_width=80,
94
        sort=False
95
    ): ...
96
```
97

98
[Environment Reporting](./environment-reporting.md)
99

100
### Import Tracking
101

102
Track all imports during a Python session and generate reports based on the tracked packages. Useful for discovering actual package dependencies of a script or notebook.
103

104
```python { .api }
105
def track_imports() -> None: ...
106
def untrack_imports() -> None: ...
107

108
class TrackedReport(Report):
109
    def __init__(
110
        self,
111
        additional=None,
112
        ncol=3,
113
        text_width=80,
114
        sort=False
115
    ): ...
116
```
117

118
[Import Tracking](./import-tracking.md)
119

120
### Version and Environment Utilities
121

122
Utility functions for package version detection, version comparison, and environment detection capabilities.
123

124
```python { .api }
125
def get_version(module) -> tuple[str, str | None]: ...
126
def meets_version(version: str, meets: str) -> bool: ...
127
def version_tuple(v: str) -> tuple[int, ...]: ...
128
def in_ipython() -> bool: ...
129
def in_ipykernel() -> bool: ...
130
def get_standard_lib_modules() -> set[str]: ...
131
```
132

133
[Utilities](./utilities.md)
134

135
## Command Line Interface
136

137
Scooby provides a command-line interface for generating environment reports from the terminal.
138

139
```bash
140
# Basic report with default optional packages
141
scooby
142

143
# Report with specific packages
144
scooby numpy pandas matplotlib
145

146
# Auto-generate report for a package and its dependencies
147
scooby --report numpy
148
scooby -r matplotlib
149

150
# Disable default optional packages
151
scooby --no-opt
152

153
# Sort packages alphabetically
154
scooby --sort
155

156
# Show version only
157
scooby --version
158
scooby -v
159

160
# Combine flags
161
scooby --report numpy --sort --no-opt
162
```
163

164
## Types
165

166
```python { .api }
167
# Type aliases for common parameter types  
168
PackageSpec = str | ModuleType
169
PackageList = list[PackageSpec] | None
170
MetaInfo = tuple[tuple[str, str], ...] | list[tuple[str, str]] | None
171

172
# Aliases
173
doo = Report  # Alternative name for Report class - allows scooby.doo()
174

175
# Constants
176
MODULE_NOT_FOUND = 'Module not found'
177
MODULE_TROUBLE = 'Trouble importing' 
178
VERSION_NOT_FOUND = 'Version unknown'
179
```