(help-parse-stata-logs)=

# parse-stata-logs.py - Extract Stata system information from log files

::::{warning}

This documentation was AI-generated by Claude Code and should be reviewed for accuracy. Please report any errors or inconsistencies.

::::

## Description

Recursively scans a folder for Stata system log files (`system-*.log`, `system_*.log`, `system__*.log`) and extracts the Stata version and processor licensing information recorded in each log's `creturn list` block. Results are grouped by identical value combinations (so many logs sharing the same environment print once) and printed as a Markdown report.

## Usage

```bash
python tools/parse-stata-logs.py <root_folder>
```

### Arguments

- **root_folder** - Directory to search recursively for Stata system log files.

## Extracted Fields

From each log's `creturn list` block:

- `c(stata_name)` - Stata name
- `c(stata_version)` - Stata version
- `c(version)` - Version (set)
- `c(born_date)` - Build date
- `c(edition_real)` - Edition
- `c(processors_lic)` - Processors (licensed)
- `c(processors_max)` - Processors (max usable)

## Example Output

```markdown
# Stata System Information

Root folder: `/path/to/replication`

Found **3** system log file(s).

---

## Seen in 2 log file(s)

- `code/system-01.log`
- `code/system-02.log`

- Stata (c(stata_name) c(stata_version)): Stata/MP 18.0
- Version (c(version)): 18
- Build date (c(born_date)): 15 Apr 2026
- Edition (c(edition_real)): MP
- Processors (licensed) (c(processors_lic)): 4
- Processors (max usable) (c(processors_max)): 4

---

## `code/system-03.log`

- *(no creturn list block found)*
```

## Requirements

- Python >= 3.6
- Standard library only (`re`, `pathlib`, `sys`)

## Notes

- Log files that cannot be read, or that lack a `creturn list` block, are still listed in the report rather than silently skipped.
- The script relies on the AEA replication template's convention of running `creturn list` inside the Stata system log so that version and licensing details are captured.