0
# xattr
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: xattr
7
- **Language**: Python
8
- **Installation**: `pip install xattr`
9
10
## Core Imports
11
12
```python
13
import xattr
14
```
15
16
For using the main class:
17
18
```python
19
from xattr import xattr
20
```
21
22
For convenience functions:
23
24
```python
25
from xattr import getxattr, setxattr, listxattr, removexattr
26
```
27
28
For compatibility with pyxattr:
29
30
```python
31
from xattr import pyxattr_compat
32
```
33
34
## Basic Usage
35
36
```python
37
import xattr
38
39
# Create xattr wrapper for a file
40
x = xattr.xattr('/path/to/file')
41
42
# Set an extended attribute (values must be bytes)
43
x['user.description'] = b'This is my file'
44
45
# Get an extended attribute
46
description = x['user.description'] # Returns bytes
47
48
# List all extended attributes
49
attrs = x.list() # Returns list of strings
50
51
# Check if attribute exists
52
if 'user.description' in x:
53
print("Description exists")
54
55
# Remove an attribute
56
del x['user.description']
57
58
# Use convenience functions
59
xattr.setxattr('/path/to/file', 'user.title', b'My Document')
60
title = xattr.getxattr('/path/to/file', 'user.title')
61
all_attrs = xattr.listxattr('/path/to/file')
62
```
63
64
## Architecture
65
66
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).
67
68
The xattr package provides multiple interfaces:
69
- **xattr class**: Dict-like interface wrapping a path or file descriptor
70
- **Convenience functions**: Simple function-based API for one-off operations
71
- **Compatibility layer**: pyxattr-compatible API for migration
72
- **Command line tool**: Interactive attribute management
73
74
## Capabilities
75
76
### Dict-like Interface
77
78
The primary interface for extended attribute manipulation through the xattr class, providing complete dict-like semantics for working with file attributes.
79
80
```python { .api }
81
class xattr:
82
def __init__(self, obj, options=0): ...
83
def get(self, name, options=0, *, default=None): ...
84
def set(self, name, value, options=0): ...
85
def remove(self, name, options=0): ...
86
def list(self, options=0): ...
87
# Dict interface methods
88
def __getitem__(self, key): ...
89
def __setitem__(self, key, value): ...
90
def __delitem__(self, key): ...
91
def keys(self): ...
92
def values(self): ...
93
def items(self): ...
94
```
95
96
[Dict-like Interface](./dict-interface.md)
97
98
### Convenience Functions
99
100
Simple function-based API for direct extended attribute operations without creating xattr objects, ideal for one-off operations.
101
102
```python { .api }
103
def getxattr(f, attr, symlink=False): ...
104
def setxattr(f, attr, value, options=0, symlink=False): ...
105
def listxattr(f, symlink=False): ...
106
def removexattr(f, attr, symlink=False): ...
107
```
108
109
[Convenience Functions](./convenience-functions.md)
110
111
### pyxattr Compatibility
112
113
Compatibility layer providing pyxattr-compatible API for easy migration from the pyxattr package, with namespace support and different calling conventions.
114
115
```python { .api }
116
# Namespace constants
117
NS_SECURITY: bytes
118
NS_USER: bytes
119
NS_SYSTEM: bytes
120
NS_TRUSTED: bytes
121
122
def get(item, name, nofollow=False, namespace=None): ...
123
def set(item, name, value, nofollow=False, flags=0, namespace=None): ...
124
def list(item, nofollow=False, namespace=None): ...
125
def remove(item, name, nofollow=False, namespace=None): ...
126
```
127
128
[pyxattr Compatibility](./pyxattr-compatibility.md)
129
130
### Command Line Tool
131
132
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.
133
134
```bash { .api }
135
xattr [-slz] file [file ...] # List attributes
136
xattr -p [-slz] attr_name file [file ...] # Print attribute value
137
xattr -w [-sz] attr_name attr_value file [file ...] # Write attribute value
138
xattr -d [-s] attr_name file [file ...] # Delete attribute
139
xattr -c [-s] file [file ...] # Clear all attributes
140
```
141
142
[Command Line Tool](./command-line-tool.md)
143
144
## Constants
145
146
```python { .api }
147
# Option flags
148
XATTR_NOFOLLOW: int # Don't follow symbolic links
149
XATTR_CREATE: int # Fail if attribute already exists
150
XATTR_REPLACE: int # Fail if attribute doesn't exist
151
XATTR_NOSECURITY: int # Bypass security checks (macOS)
152
153
# Platform limits
154
XATTR_MAXNAMELEN: int # Maximum attribute name length
155
156
# macOS special attributes
157
XATTR_FINDERINFO_NAME: str # "com.apple.FinderInfo"
158
XATTR_RESOURCEFORK_NAME: str # "com.apple.ResourceFork"
159
160
# Platform compatibility
161
XATTR_COMPAT_USER_PREFIX: str # Platform-specific user namespace prefix (Linux: "user.", others: "")
162
```
163
164
## Types
165
166
```python { .api }
167
# All attribute values must be bytes
168
# Attribute names are strings (UTF-8 encoded internally)
169
# File objects can be: str paths, int file descriptors, or file-like objects with fileno()
170
```
171
172
## Error Handling
173
174
The library raises standard Python exceptions:
175
176
- `IOError`/`OSError`: Filesystem-level errors (permission denied, file not found, etc.)
177
- `KeyError`: Missing attributes when using dict-like interface
178
- `TypeError`: Invalid value types (attribute values must be bytes)
179
180
## Platform Notes
181
182
- **Linux**: Custom attributes require 'user.' namespace prefix (handled automatically)
183
- **macOS**: Supports special attributes like Finder info and resource forks
184
- **All platforms**: Attribute values are always bytes, names are UTF-8 strings