dictree-print 0.1.0
A lightweight tool to visualize the structure of nested Python dictionaries and lists as a tree.
Requires Python: >=3.10
Keywords: dict, tree, structure, visualize, schema, debug

# Dictree (dictree-sprint)

[![PyPI version](https://img.shields.io/pypi/v/dictree-sprint.svg)](https://pypi.org/project/dictree-sprint/)
[![Python versions](https://img.shields.io/pypi/pyversions/dictree-sprint.svg)](https://pypi.org/project/dictree-sprint/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A lightweight Python utility to visualize the schema of nested dictionaries, lists, tuples, and sets in a tree-like structure. It helps developers quickly understand complex data structures without getting lost in the actual values.

[中文文档 (Chinese Documentation)](README_zh.md)

---

## 🚀 Features

- **Structured Visualization**: Emulates the Unix `tree` command style for nested objects.
- **Representative Sampling**: Automatically identifies element types in lists/sets. If a container contains dictionaries or other nested structures, it extracts their schema as a representative sample.
- **Depth Control**: Use the `max_depth` parameter to prevent infinite recursion or to handle massive objects.
- **Customizable Templates**: Customize how list/container statistics are displayed.
- **Execution Flexibility**: Supports both direct printing to the console and returning results as strings.

---

## 📦 Installation

```bash
pip install dictree-sprint
```

---

## 🛠️ Quick Start

### 1. Basic Usage

Visualize a complex nested dictionary:

```python
from dictree import sprint

data = {
    "users": [
        {
            "id": 1,
            "profile": {
                "name": "Alice",
                "hobbies": ["coding", "reading"]
            }
        },
        {
            "id": 2,
            "profile": {
                "name": "Bob",
                "hobbies": ["gaming"]
            }
        }
    ],
    "status": "success",
    "meta": {"page": 1, "total": 100}
}

sprint(data)
```

**Output:**
```text
├── users
│   └── [2]: dict
│       ├── id
│       └── profile
│           ├── name
│           └── hobbies
│               └── [2]: str
├── status
└── meta
    ├── page
    └── total
```

### 2. Limiting Depth

When dealing with very large objects, use the `max_depth` parameter:

```python
sprint(data, max_depth=1)
```

**Output:**
```text
├── users
│   └── … (depth limit)
├── status
└── meta
    └── … (depth limit)
```

### 3. Capture as String

If you need to save the output to logs or a file:

```python
tree_output = sprint(data, return_string=True)
print(f"Captured Schema Tree:\n{tree_output}")
```

### 4. Custom List Templates

Change how lists are represented using `list_repr_template`. 
The default is `"{count}: {repr}"`.

```python
sprint(data, list_repr_template="[{count} elements of {repr}]")
```

**Example Output:**
```text
├── users
│   └── [2 elements of dict]
...
```

---

## 💡 Why Dictree?

When working with JSON from web scrapers, large API responses, or complex config files, standard `print()` or `pprint` often produces thousands of lines of output. `dictree` hides the values and extracts only the keys and container types, allowing you to see the entire hierarchy and structure at a glance.

---

## 📄 License

MIT License