tessl/pypi-xattr

Python wrapper for extended filesystem attributes with dict-like interface

Overview

Eval results

Files

Command Line Tool

Name: tessl/pypi-xattr
Author: tessl

The xattr package includes a command-line tool for viewing and editing extended filesystem attributes from the shell. This tool provides a complete command-line interface for all extended attribute operations.

Installation and Access

The command-line tool is automatically installed with the package and can be accessed in multiple ways:

# Direct command (after pip install xattr)
xattr [options] file [file ...]

# As Python module
python -m xattr [options] file [file ...]

# Using the tool module directly
python -m xattr.tool [options] file [file ...]

Capabilities

List Attributes (Default)

List the names of all extended attributes on files.

xattr [-slz] file [file ...]

Parameters:

file: Path to file(s) to examine
-s: Act on symbolic links themselves rather than their targets
-l: Print long format (attr_name: attr_value)
-z: Compress or decompress attribute values in zip format

Usage Examples:

# List attribute names for a file
xattr /path/to/file

# List attributes for multiple files
xattr file1.txt file2.txt /path/to/dir

# List attributes on symlink itself (not target)
xattr -s /path/to/symlink

# List in long format (show names and values)
xattr -l /path/to/file

# Handle compressed attributes
xattr -lz /path/to/file

Print Attribute Value

Print the value of a specific extended attribute.

xattr -p [-slz] attr_name file [file ...]

Parameters:

-p: Print mode - show attribute value
attr_name: Name of the attribute to display
file: Path to file(s) to examine
-s: Act on symbolic links themselves
-l: Show in long format with hex dump for binary data
-z: Decompress attribute if compressed

Usage Examples:

# Print specific attribute value
xattr -p user.description /path/to/file

# Print from multiple files
xattr -p user.title file1.txt file2.txt

# Print with hex dump for binary data
xattr -pl user.binary_data /path/to/file

# Print compressed attribute
xattr -pz user.compressed_info /path/to/file

Write Attribute Value

Set the value of an extended attribute.

xattr -w [-sz] attr_name attr_value file [file ...]

Parameters:

-w: Write mode - set attribute value
attr_name: Name of the attribute to set
attr_value: Value to assign (will be encoded as UTF-8 bytes)
file: Path to file(s) to modify
-s: Act on symbolic links themselves
-z: Compress attribute value in zip format

Usage Examples:

# Set attribute value
xattr -w user.description "This is my important file" /path/to/file

# Set on multiple files
xattr -w user.author "John Doe" file1.txt file2.txt

# Set on symlink itself
xattr -ws user.link_type "shortcut" /path/to/symlink  

# Set compressed attribute
xattr -wz user.large_data "Large content that will be compressed" /path/to/file

Delete Attribute

Remove a specific extended attribute.

xattr -d [-s] attr_name file [file ...]

Parameters:

-d: Delete mode - remove attribute
attr_name: Name of the attribute to remove
file: Path to file(s) to modify
-s: Act on symbolic links themselves

Usage Examples:

# Remove specific attribute
xattr -d user.old_description /path/to/file

# Remove from multiple files
xattr -d user.temp_data file1.txt file2.txt

# Remove from symlink itself
xattr -ds user.link_info /path/to/symlink

Clear All Attributes

Remove all extended attributes from files.

xattr -c [-s] file [file ...]

Parameters:

-c: Clear mode - remove all attributes
file: Path to file(s) to modify
-s: Act on symbolic links themselves

Usage Examples:

# Clear all attributes from a file
xattr -c /path/to/file

# Clear attributes from multiple files
xattr -c file1.txt file2.txt /path/to/dir

# Clear attributes from symlink itself
xattr -cs /path/to/symlink

Help

Display usage information and available options.

xattr -h
xattr --help

Complete Workflow Examples

File Metadata Management

# Add metadata to a document
xattr -w user.title "Project Proposal" document.pdf
xattr -w user.author "Jane Smith" document.pdf  
xattr -w user.version "1.0" document.pdf
xattr -w user.tags "project,proposal,draft" document.pdf

# View all metadata
xattr -l document.pdf

# Update specific metadata
xattr -w user.version "1.1" document.pdf

# Check specific attribute
xattr -p user.author document.pdf

# Remove temporary attributes
xattr -d user.temp_notes document.pdf

# Clean up all metadata when done
xattr -c document.pdf

Batch Operations

# Set the same attribute on multiple files
xattr -w user.project "WebApp" *.html *.css *.js

# List attributes for all files in directory
xattr /path/to/project/*

# Remove specific attribute from all project files  
xattr -d user.old_version /path/to/project/*

# View detailed attributes for all files
xattr -l /path/to/project/*

Working with Symlinks

# Create symlink
ln -s /original/file /path/to/symlink

# Set attribute on original file (default)
xattr -w user.description "Original file" /path/to/symlink

# Set attribute on symlink itself
xattr -ws user.link_info "Points to original" /path/to/symlink

# Compare attributes
echo "Original file attributes:"
xattr -l /original/file
echo "Symlink attributes:"  
xattr -ls /path/to/symlink

Output Formats

Standard List Format

$ xattr /path/to/file
user.description
user.title
user.version

Long Format (-l)

$ xattr -l /path/to/file
user.description: My important document
user.title: Project Proposal
user.version: 1.0

Multiple Files

$ xattr file1.txt file2.txt
file1.txt: user.author
file1.txt: user.version
file2.txt: user.title
file2.txt: user.tags

Binary Data Hex Dump

When attribute values contain binary data or null bytes, the tool automatically switches to hex dump format:

$ xattr -pl user.binary_data /path/to/file
user.binary_data:
0000   89 50 4E 47 0D 0A 1A 0A   .PNG....
0008   00 00 00 0D 49 48 44 52   ....IHDR

Error Handling

The command-line tool provides clear error messages for common issues:

# File not found
$ xattr /nonexistent/file
No such file: /nonexistent/file

# Attribute not found  
$ xattr -p user.missing /path/to/file
No such xattr: user.missing

# Permission denied
$ xattr -w user.test "value" /protected/file
Operation not permitted

# Invalid operation combinations
$ xattr -pw user.attr "value" /path/to/file
-p not allowed with -w

Platform Notes

Linux: User attributes require 'user.' namespace prefix (handled automatically)
macOS: Supports special attributes like Finder info and resource forks
All platforms: Symbolic link handling varies by filesystem support

Exit Codes

0: Success - all operations completed without errors
1: Partial failure - some operations failed but others succeeded
64: Usage error - invalid command line arguments

Install with Tessl CLI

npx tessl i tessl/pypi-xattr

docs

command-line-tool.md

convenience-functions.md

dict-interface.md

index.md

pyxattr-compatibility.md

tile.json

tessl/pypi-xattr