Usage Guide for modelinfo¶

This guide will help you begin using django-model-info to explore your Django models.

Basic Usage¶

Quick Start Command¶

The simplest way to use django-model-info is:

python manage.py modelinfo

This will display information about all models in your project using the default verbosity level (2).

For specific apps, models, or a combination, add them to the command. Any of the following formats are valid:

python manage.py modelinfo sales
python manage.py modelinfo sales.Order
python manage.py modelinfo sales.Order sales.OrderItem auth

Understanding Default Output¶

The default output (verbosity level 2) includes:

Model Information

sales.Order
├── Model Info
│   ├── Model Name: Order
│   ├── Verbose Name: order
|   ├── Verbose Name Plural: orders
│   └── ...
├── Fields
│   ├── Regular Fields (Field Name | Field Type | Database Column | Database Type | Verbose Name)
│   ├── Relations (Field Name | Field Type | Database Column | Database Type | Related Model | Related Name)
│   └── Reverse Relations (Field Name | Field Type Database Type | Related Model | Field Name on Related Model | Field Type on Related Model)
├── Methods
│   ├── Other Methods (Method Name | Signature)
│   ├── Private Methods (Method Name | Signature)
│   ├── Dunder Methods (Method Name | Signature)
│   └── Common Django Methods (Method Name | Signature)
└── Custom Managers
    ├── Custom Managers
    └── Custom QuerySets

Each section provides:

Model Info: Basic model configuration and metadata
Fields: All model fields with their types and properties
Methods: Available model methods with signatures
Custom Managers: Custom managers and querysets

Common Use Cases¶

1. Exploring a New Project¶

When joining a project or returning after time away:

# Get a high-level overview of all models
python manage.py modelinfo -v 1

# Deep dive into a specific app
python manage.py modelinfo sales -v 3

This helps you:

Understand the project’s data structure
Identify key models and their relationships
Find important fields and methods

2. Documenting Models¶

Generate documentation for your models:

# Generate HTML documentation
python manage.py modelinfo -o models.html

# Generate Markdown for your repo
python manage.py modelinfo -o models.md

Tips for documentation:

Use verbosity level 2 or 3 for comprehensive documentation
Filter by app to create focused documentation sections
Include the output in your project’s documentation

3. Debugging Relationships¶

When working with model relationships:

# Focus on a specific model with full details
python manage.py modelinfo sales.Order -v 3

This helps you:

View all forward and reverse relationships
Understand how models are connected
Find related field names for queries
Identify potential optimization points

Pro tip: When debugging relationships, pay special attention to the “Relations” and “Reverse Relations” sections in the output. These show how your model connects to others and what field names to use in queries.

Configuration & Options¶

The modelinfo command can be configured through both Django settings and command-line options. All settings are optional, and should be added as dictionary key-value entries in the DJANGO_MODELINFO setting.

MODELINFO_VERBOSITY¶

Controls the default level of detail in the output.

# settings.py
DJANGO_MODELINFO = {
    "MODELINFO_VERBOSITY": 2  # Default value
}

Valid Options¶

0: Model names only
- Best for: Quick overview of available models
- Use when: You need a simple list of models
```
# Output Example:
sales.BankAccount
sales.Order
sales.OrderItem
```
1: Basic information
- Best for: General model exploration
- Shows: Model names, field names, basic method names
- Use when: You need to know what fields and methods exist
```
# Output includes:
- Field names (without details)
- Method names (without signatures)
- Basic model properties
```
2: Detailed information (Default)
- Best for: Daily development work
- Shows: Field details, method signatures, relationships
- Use when: You need to understand model structure
```
# Output includes:
- Field types and properties
- Method signatures
- Relationship details
```
3: Complete information
- Best for: Documentation and deep analysis
- Shows: Everything including docstrings and source locations
- Use when: You need full understanding or documentation
```
# Output includes:
- All level 2 information
- Method docstrings
- Source file locations
- Line numbers
```

MODELINFO_FILTER¶

Specifies which models or apps to display by default.

# settings.py
DJANGO_MODELINFO = {
    "MODELINFO_FILTER": ["sales", "auth.User"]
}

Format Specifications¶

App Filter: Just the app name (e.g., "sales")
Model Filter: App and model name separated by dot (e.g., "sales.Order")
Multiple Items: List of strings with any combination

Example Patterns¶

# Show multiple apps
MODELINFO_FILTER = ["auth", "sales", "inventory"]

# Show specific models
MODELINFO_FILTER = ["auth.User", "sales.Order"]

# Mix of apps and models
MODELINFO_FILTER = ["auth", "sales.Order", "inventory.Product"]

Command Line Options¶

Verbosity Levels (`-v`, `--verbosity`)¶

Override the default verbosity level:

# Model names only
python manage.py modelinfo -v 0

# Basic information
python manage.py modelinfo -v 1

# Detailed information (default)
python manage.py modelinfo -v 2

# Complete information
python manage.py modelinfo -v 3

Filtering (positional arg)¶

Filter which models to display:

# Single app
python manage.py modelinfo sales

# Single model
python manage.py modelinfo sales.Order

# Multiple filters
python manage.py modelinfo sales auth.User

By App¶

Shows all models in specified app(s):

python manage.py modelinfo auth
python manage.py modelinfo auth orders

By Model¶

Shows specific model(s):

python manage.py modelinfo auth.User
python manage.py modelinfo auth.User sales.Order

Multiple Filters¶

Combine app and model filters:

python manage.py modelinfo auth sales.Order inventory

Output Options (`-o`, `--output`)¶

Export the output in different formats:

HTML Format¶

python manage.py modelinfo -o output.html

Includes rich formatting and styling
Interactive navigation (if supported by the template)
Ideal for documentation websites

Markdown Format¶

python manage.py modelinfo - output.md

Perfect for GitHub documentation
Easy to read in plain text
Can be converted to other formats

Text Format¶

python manage.py modelinfo -o output.txt

Plain text output
No formatting
Useful for processing with other tools

Other Options¶

`--exclude-defaults`¶

Excludes Django’s default fields and methods:

python manage.py modelinfo --exclude-defaults

Hides common Django fields (e.g., id, created_at)
Excludes standard model methods
Shows only custom fields and methods

`--markdown`¶

Outputs in markdown format directly to console:

python manage.py modelinfo --markdown

Useful for copying into documentation
No file creation needed
Can be piped to other commands

Option Precedence¶

When options are specified in multiple places, they are prioritized as follows:

Command line options (highest priority)
Django settings
Default values (lowest priority)