SPSS Metadata Printer 📊
Easy-to-use Python package for extracting, viewing, and exporting metadata from SPSS files with beautiful formatting.
✨ Features
- 📋 Pretty-print comprehensive SPSS metadata to console
- 💾 Export metadata summaries to text files automatically saved to Downloads
- 📄 Extract metadata dictionary to JSON for programmatic access and archival
- 🏷️ Create label mappings from Excel for structured variable labeling
- 📊 Detailed variable information including labels, types, and value mappings
- 🎨 Beautiful table formatting with configurable width and display options
🚀 Quick Start
Installation
pip install metaprinter
Or using uv:
uv add metaprinter
Basic Usage
from metaprinter import print_metadata, export_metadata, extract_metadict, make_labels
import pyreadstat
# Load your SPSS file
df, meta = pyreadstat.read_sav('data.sav')
# Display beautiful metadata summary inside a notebook
print_summary = print_metadata(df, meta)
# Export to Downloads/metadata_summary.txt
export_summary = export_metadata(df, meta)
# Extract metadata to JSON (Downloads/meta_dictionary.json)
extract_metadict(meta)
# Create label mappings from Excel
col_labels, val_labels = make_labels("label_mappings.xlsx")
Output Preview:
============================================================
SPSS FILE METADATA
============================================================
File encoding : 'UTF-8'
Number of cols : 25
Number of rows : 100
Table name : 'Table'
File label : 'Customer Satisfaction Survey'
Notes : 'Notes'
VARIABLE METADATA
============================================================
┌───────────────┬─────────┬──────────┬───────────┬──────────────┬─────────────────────┬─────────────────────┐
│ column ┆ dtype ┆ column_n ┆ n_uniques ┆ n_categories ┆ column_label ┆ value_labels │
│ --- ┆ --- ┆ --- ┆ --- ┆ --- ┆ --- ┆ --- │
│ str ┆ str ┆ i64 ┆ i64 ┆ i64 ┆ str ┆ str │
╞═══════════════╪═════════╪══════════╪═══════════╪══════════════╪═════════════════════╪═════════════════════╡
│ respondent_id ┆ Int64 ┆ 1547 ┆ 1547 ┆ 0 ┆ Respondent ID ┆ │
│ satisfaction ┆ Int64 ┆ 1523 ┆ 5 ┆ 5 ┆ Satisfaction Level ┆ { │
│ ┆ ┆ ┆ ┆ ┆ ┆ "1": "Very Low", │
│ ┆ ┆ ┆ ┆ ┆ ┆ "2": "Low", │
│ ┆ ┆ ┆ ┆ ┆ ┆ "3": "Neutral", │
│ ┆ ┆ ┆ ┆ ┆ ┆ "4": "High", │
│ ┆ ┆ ┆ ┆ ┆ ┆ "5": "Very High" │
│ ┆ ┆ ┆ ┆ ┆ ┆ } │
│ age ┆ Int64 ┆ 1534 ┆ 6 ┆ 6 ┆ Age Group Category ┆ { │
│ ┆ ┆ ┆ ┆ ┆ ┆ "1": "18-25", │
│ ┆ ┆ ┆ ┆ ┆ ┆ "2": "26-35", │
│ ┆ ┆ ┆ ┆ ┆ ┆ "3": "36-45", │
│ ┆ ┆ ┆ ┆ ┆ ┆ "4": "46-55", │
│ ┆ ┆ ┆ ┆ ┆ ┆ "5": "56-65", │
│ ┆ ┆ ┆ ┆ ┆ ┆ "6": "65+" │
│ ┆ ┆ ┆ ┆ ┆ ┆ } │
│ ... ┆ ... ┆ ... ┆ ... ┆ ... ┆ ... ┆ ... │
└───────────────┴─────────┴──────────┴───────────┴──────────────┴─────────────────────┴─────────────────────┘
📖 API Reference
print_metadata(df, meta, show_all_columns=True, max_width=222, include_all=False)
Print a comprehensive metadata summary for SPSS data loaded with pyreadstat.
Parameters:
df: DataFrame containing the SPSS data (Pandas or Polars)meta: Metadata object frompyreadstat.read_sav()show_all_columns: Whether to show all columns without truncation (default: True, optional)max_width: Maximum table width in characters (default: 222, optional)include_all: Whether to include all available metadata fields (default: False, optional)
export_metadata(df, meta, filename=None, show_all_columns=True, max_width=222, include_all=False)
Export SPSS metadata summary to a text file in the Downloads folder.
Parameters:
df: DataFrame containing the SPSS data (Pandas or Polars)meta: Metadata object frompyreadstat.read_sav()filename: Custom filename without extension (default: "metadata_summary")show_all_columns: Whether to show all columns without truncation (default: True, optional)max_width: Maximum table width in characters (default: 222, optional)include_all: Whether to include all available metadata fields (default: False, optional)
extract_metadict(meta, include_all=False, output_path=None)
Extract metadata dictionary from pyreadstat meta object and save as JSON.
Parameters:
meta: Metadata object frompyreadstat.read_sav()include_all: Whether to include all metadata fields or just essential ones (default: False, optional)output_path: Custom file path for JSON output (must end with .json). If None, saves to Downloads/meta_dictionary.json (default: None, optional)
Example JSON Output (basic):
{
"General Information": {
"Notes": "Survey conducted in 2024",
"Creation Time": "2024-01-15 10:30:00",
"File Encoding": "UTF-8",
"Number of Columns": 25,
"Number of Rows": 100,
"Table Name": "Table",
"File Label": "Customer Satisfaction Survey"
},
"Variable Information": {
"Column Names to Labels": {
"respondent_id": "Respondent ID",
"satisfaction": "Satisfaction Level",
"age": "Age Group Category"
},
"Variable Value Labels": {
"satisfaction": {
"1": "Very Low",
"2": "Low",
"3": "Neutral",
"4": "High",
"5": "Very High"
}
}
}
}
make_labels(input_path, output_path=None, ...)
Transform Excel file with label mappings into Python dictionaries for column labels and value labels.
Parameters:
input_path(str): Path to Excel file containing label mappingsoutput_path(str, optional): Path for output Python file. If None, no file is created (default: None)col_label_sheet(str, optional): Name of sheet with column labels (default: "col_label")value_label_sheet(str, optional): Name of sheet with value labels (default: "value_label")col_dict_name(str, optional): Name for column labels dictionary in output (default: "user_column_labels")value_dict_name(str, optional): Name for value labels dictionary in output (default: "user_variable_value_labels")col_quote_style(str, optional): Quote style for column labels (default:''')value_quote_style(str, optional): Quote style for value labels (default:''')col_variable_column(str, optional): Variable name column in col_label sheet (default: "variable")col_label_column(str, optional): Label column in col_label sheet (default: "label")value_variable_column(str, optional): Variable name column in value_label sheet (default: "variable")value_value_column(str, optional): Value/code column in value_label sheet (default: "value")value_label_column(str, optional): Label column in value_label sheet (default: "label")verbose(bool, optional): Print progress messages (default: True)
Returns:
- Tuple of (column_labels_dict, value_labels_dict)
Excel Structure:
Your Excel file should have two sheets:
-
Column Labels Sheet (default name: "col_label"):
variable label age Age of respondent gender Gender income Annual household income -
Value Labels Sheet (default name: "value_label"):
variable value label gender 1 Male gender 2 Female income 1 Under $25k income 2 $25k-$50k
Usage Examples:
from metaprinter import make_labels
# Basic usage - creates Python file and returns dictionaries
col_labels, val_labels = make_labels(
input_path="survey_labels.xlsx",
output_path="survey_labels.py"
)
# Return only (no file output) - perfect for notebooks
col_labels, val_labels = make_labels("survey_labels.xlsx")
Output File Example (when output_path is provided):
user_column_labels = {
'age': '''Age of respondent''',
'gender': '''Gender''',
'income': '''Annual household income''',
}
user_variable_value_labels = {
'gender': {
1: 'Male',
2: 'Female',
},
'income': {
1: 'Under $25k',
2: '$25k-$50k',
},
}
📋 Requirements
- Python >=3.11
- pyreadstat >=1.3.0
- polars >=1.3.0
- pandas >=2.3.0
📝 License
MIT License - see LICENSE file for details
🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Metadata
Release files for metaprinter 0.2.9
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| metaprinter-0.2.9.tar.gz | 10.0 kB | Without provenance | Details for metaprinter-0.2.9.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| metaprinter-0.2.9-py3-none-any.whl | Python 3 | none | any | Details for metaprinter-0.2.9-py3-none-any.whl |
Total release size: 21.7 kB
Release files / metaprinter-0.2.9.tar.gz
| Download URL | metaprinter-0.2.9.tar.gz |
|---|---|
| Size | 10.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
14cbdd599a910ca0cc22c307a2eb0236c4d8d8787435ba04ada24adfec2c4399
|
|
BLAKE2b-256 checksum How to use checksums |
e9f91ae1baecc2bc23f372b879090bb536b1b11839fedcc4e87c114ac8f3a139
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.5
|
Release files / metaprinter-0.2.9-py3-none-any.whl
| Download URL | metaprinter-0.2.9-py3-none-any.whl |
|---|---|
| Size | 11.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
03d60401761b1ea41e31c9ad9fd92e20b893db79161cb6e20d71b00f5b56ff03
|
|
BLAKE2b-256 checksum How to use checksums |
9442131fe6c7210e068b2db7bebdaafd91e162e78440433e7272efb81281acc5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.5
|
Security for metaprinter 0.2.9
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.