tessl/pypi-xattr

Python wrapper for extended filesystem attributes with dict-like interface

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

xattr

Name: tessl/pypi-xattr
Author: tessl

Python wrapper for extended filesystem attributes, providing a dict-like interface for reading, writing, and manipulating extended attributes on files and directories across Unix-like systems. Supports Darwin 8.0+ (Mac OS X 10.4), Linux 2.6+, with experimental support for Solaris and FreeBSD.

Package Information

Package Name: xattr
Language: Python
Installation: pip install xattr

Core Imports

import xattr

For using the main class:

from xattr import xattr

For convenience functions:

from xattr import getxattr, setxattr, listxattr, removexattr

For compatibility with pyxattr:

from xattr import pyxattr_compat

Basic Usage

import xattr

# Create xattr wrapper for a file
x = xattr.xattr('/path/to/file')

# Set an extended attribute (values must be bytes)
x['user.description'] = b'This is my file'

# Get an extended attribute
description = x['user.description']  # Returns bytes

# List all extended attributes
attrs = x.list()  # Returns list of strings

# Check if attribute exists
if 'user.description' in x:
    print("Description exists")

# Remove an attribute
del x['user.description']

# Use convenience functions
xattr.setxattr('/path/to/file', 'user.title', b'My Document')
title = xattr.getxattr('/path/to/file', 'user.title')
all_attrs = xattr.listxattr('/path/to/file')

Architecture

Extended attributes extend the basic attributes of files and directories in the file system. They are stored as name:data pairs associated with file system objects (files, directories, symlinks, etc).

The xattr package provides multiple interfaces:

xattr class: Dict-like interface wrapping a path or file descriptor
Convenience functions: Simple function-based API for one-off operations
Compatibility layer: pyxattr-compatible API for migration
Command line tool: Interactive attribute management

Capabilities

Dict-like Interface

The primary interface for extended attribute manipulation through the xattr class, providing complete dict-like semantics for working with file attributes.

class xattr:
    def __init__(self, obj, options=0): ...
    def get(self, name, options=0, *, default=None): ...
    def set(self, name, value, options=0): ...
    def remove(self, name, options=0): ...
    def list(self, options=0): ...
    # Dict interface methods
    def __getitem__(self, key): ...
    def __setitem__(self, key, value): ...
    def __delitem__(self, key): ...
    def keys(self): ...
    def values(self): ...
    def items(self): ...

Dict-like Interface

Convenience Functions

Simple function-based API for direct extended attribute operations without creating xattr objects, ideal for one-off operations.

def getxattr(f, attr, symlink=False): ...
def setxattr(f, attr, value, options=0, symlink=False): ...
def listxattr(f, symlink=False): ...
def removexattr(f, attr, symlink=False): ...

Convenience Functions

pyxattr Compatibility

Compatibility layer providing pyxattr-compatible API for easy migration from the pyxattr package, with namespace support and different calling conventions.

# Namespace constants
NS_SECURITY: bytes
NS_USER: bytes
NS_SYSTEM: bytes
NS_TRUSTED: bytes

def get(item, name, nofollow=False, namespace=None): ...
def set(item, name, value, nofollow=False, flags=0, namespace=None): ...
def list(item, nofollow=False, namespace=None): ...
def remove(item, name, nofollow=False, namespace=None): ...

pyxattr Compatibility

Command Line Tool

Interactive command-line interface for extended attribute management, providing shell access to all xattr functionality with comprehensive options for listing, reading, writing, and removing attributes.

xattr [-slz] file [file ...]                          # List attributes
xattr -p [-slz] attr_name file [file ...]             # Print attribute value  
xattr -w [-sz] attr_name attr_value file [file ...]   # Write attribute value
xattr -d [-s] attr_name file [file ...]               # Delete attribute
xattr -c [-s] file [file ...]                         # Clear all attributes

Command Line Tool

Constants

# Option flags
XATTR_NOFOLLOW: int      # Don't follow symbolic links
XATTR_CREATE: int        # Fail if attribute already exists
XATTR_REPLACE: int       # Fail if attribute doesn't exist
XATTR_NOSECURITY: int    # Bypass security checks (macOS)

# Platform limits
XATTR_MAXNAMELEN: int    # Maximum attribute name length

# macOS special attributes
XATTR_FINDERINFO_NAME: str     # "com.apple.FinderInfo"
XATTR_RESOURCEFORK_NAME: str   # "com.apple.ResourceFork"

# Platform compatibility
XATTR_COMPAT_USER_PREFIX: str  # Platform-specific user namespace prefix (Linux: "user.", others: "")

Types

# All attribute values must be bytes
# Attribute names are strings (UTF-8 encoded internally)
# File objects can be: str paths, int file descriptors, or file-like objects with fileno()

Error Handling

The library raises standard Python exceptions:

IOError/OSError: Filesystem-level errors (permission denied, file not found, etc.)
KeyError: Missing attributes when using dict-like interface
TypeError: Invalid value types (attribute values must be bytes)

Platform Notes

Linux: Custom attributes require 'user.' namespace prefix (handled automatically)
macOS: Supports special attributes like Finder info and resource forks
All platforms: Attribute values are always bytes, names are UTF-8 strings

Workspace: tessl
Visibility: Public
Created: 7 months ago
Last updated: 2 months ago
Describes: pkg:pypi/xattr@1.2.x
Publish Source: CLI
Badge