0
# Environment Reporting
1

2
Generate comprehensive environment reports showing system information, Python version, and package versions. The reporting system supports both manual package specification and automatic dependency detection.
3

4
## Capabilities
5

6
### Report Class
7

8
The main reporting class that creates environment reports with customizable package lists and formatting options.
9

10
```python { .api }
11
class Report:
12
    def __init__(
13
        self,
14
        additional: list[str | ModuleType] | None = None,
15
        core: list[str | ModuleType] | None = None,
16
        optional: list[str | ModuleType] | None = None,
17
        ncol: int = 4,
18
        text_width: int = 80,
19
        sort: bool = False,
20
        extra_meta: tuple[tuple[str, str], ...] | list[tuple[str, str]] | None = None,
21
        max_width: int | None = None
22
    ):
23
        """
24
        Create an environment report.
25

26
        Parameters:
27
        - additional (list[str | ModuleType], optional): Additional packages to include
28
        - core (list[str | ModuleType], optional): Core packages to list first
29
        - optional (list[str | ModuleType], optional): Packages to include if available, defaults to ['numpy', 'scipy', 'IPython', 'matplotlib', 'scooby']
30
        - ncol (int): Number of columns in HTML table, default: 4
31
        - text_width (int): Text width for plain text output, default: 80
32
        - sort (bool): Sort packages alphabetically, default: False
33
        - extra_meta (tuple[tuple[str, str], ...] | list[tuple[str, str]], optional): Additional metadata key-value pairs
34
        - max_width (int, optional): Maximum width of HTML table
35
        """
36

37
    def __repr__(self) -> str:
38
        """Return plain text representation of the report."""
39

40
    def _repr_html_(self) -> str:
41
        """Return HTML representation for Jupyter notebooks."""
42

43
    def to_dict(self) -> dict[str, str]:
44
        """Return report data as dictionary for programmatic access."""
45

46
    @property
47
    def packages(self) -> dict[str, str]:
48
        """Dictionary of package names to version strings."""
49
```
50

51
### AutoReport Class
52

53
Automatically generate reports based on package distribution dependencies.
54

55
```python { .api }
56
class AutoReport(Report):
57
    def __init__(
58
        self,
59
        module: str | ModuleType,
60
        additional: list[str | ModuleType] | None = None,
61
        ncol: int = 3,
62
        text_width: int = 80,
63
        sort: bool = False
64
    ):
65
        """
66
        Auto-generate report for a package and its dependencies.
67

68
        Parameters:
69
        - module (str | ModuleType): Package name or module to analyze
70
        - additional (list[str | ModuleType], optional): Additional packages to include
71
        - ncol (int): Number of columns in HTML table, default: 3
72
        - text_width (int): Text width for plain text output, default: 80
73
        - sort (bool): Sort packages alphabetically, default: False
74
        """
75
```
76

77
### System Information Properties
78

79
The Report class provides access to detailed system information through properties:
80

81
```python { .api }
82
class Report:
83
    @property
84
    def system(self) -> str:
85
        """System/OS name with version details."""
86

87
    @property
88
    def platform(self) -> str:
89
        """Platform string."""
90

91
    @property
92
    def machine(self) -> str:
93
        """Machine type (e.g., 'x86_64')."""
94

95
    @property
96
    def architecture(self) -> str:
97
        """Bit architecture (e.g., '64bit')."""
98

99
    @property
100
    def cpu_count(self) -> int:
101
        """Number of CPUs in the system."""
102

103
    @property
104
    def total_ram(self) -> str:
105
        """Total RAM information (requires psutil)."""
106

107
    @property
108
    def mkl_info(self) -> str | None:
109
        """Intel MKL version info if available."""
110

111
    @property
112
    def date(self) -> str:
113
        """Current date and time."""
114

115
    @property
116
    def filesystem(self) -> str | False:
117
        """File system type (requires psutil, not available on Windows)."""
118

119
    @property
120
    def sys_version(self) -> str:
121
        """Python version information."""
122

123
    @property
124
    def python_environment(self) -> str:
125
        """Python environment type: 'Jupyter', 'IPython', or 'Python'."""
126
```
127

128
## Usage Examples
129

130
### Basic Report
131

132
```python
133
import scooby
134

135
# Create a basic report with default optional packages
136
report = scooby.Report()
137
print(report)
138
```
139

140
### Custom Package Lists
141

142
```python
143
import scooby
144
import numpy
145

146
# Report with specific core and additional packages
147
report = scooby.Report(
148
    core=['numpy', 'scipy'],
149
    additional=['pandas', 'matplotlib'],
150
    optional=['seaborn', 'plotly']  # Only show if installed
151
)
152
print(report)
153

154
# Pass module objects instead of strings
155
report = scooby.Report(additional=[numpy])
156
print(report)
157
```
158

159
### Formatting Options
160

161
```python
162
import scooby
163

164
# Customize text formatting
165
report = scooby.Report(
166
    text_width=120,
167
    ncol=2,
168
    sort=True
169
)
170

171
# Add custom metadata
172
report = scooby.Report(
173
    extra_meta=[
174
        ("Project", "My Analysis"),
175
        ("Date", "2024-01-15")
176
    ]
177
)
178

179
# HTML formatting for Jupyter
180
report = scooby.Report(max_width=800)
181
html_output = report._repr_html_()
182
```
183

184
### AutoReport Usage
185

186
```python
187
import scooby
188

189
# Generate report for numpy and all its dependencies
190
auto_report = scooby.AutoReport('numpy')
191
print(auto_report)
192

193
# Include additional packages beyond dependencies
194
auto_report = scooby.AutoReport(
195
    'matplotlib',
196
    additional=['seaborn', 'plotly']
197
)
198
print(auto_report)
199
```
200

201
### Programmatic Access
202

203
```python
204
import scooby
205

206
report = scooby.Report(additional=['numpy', 'pandas'])
207

208
# Access report data as dictionary
209
data = report.to_dict()
210
print(f"Python version: {data['Python']}")
211
print(f"NumPy version: {data.get('numpy', 'Not installed')}")
212

213
# Access individual packages
214
for package, version in report.packages.items():
215
    print(f"{package}: {version}")
216
```
217

218
### Inheritance Example
219

220
```python
221
import scooby
222

223
class ProjectReport(scooby.Report):
224
    def __init__(self, additional=None, **kwargs):
225
        # Define project-specific core and optional packages
226
        core = ['numpy', 'pandas', 'matplotlib']
227
        optional = ['seaborn', 'plotly', 'bokeh']
228
        
229
        super().__init__(
230
            additional=additional,
231
            core=core,
232
            optional=optional,
233
            **kwargs
234
        )
235

236
# Use custom report class
237
report = ProjectReport(additional=['sklearn'])
238
print(report)
239
```