0
# pyxattr Compatibility
1

2
Compatibility layer providing pyxattr-compatible API for easy migration from the pyxattr package. This module handles different calling conventions, namespace support, and byte string operations to match pyxattr behavior.
3

4
## Import
5

6
```python
7
from xattr import pyxattr_compat
8
```
9

10
## Capabilities
11

12
### Namespace Constants
13

14
Predefined namespace prefixes for extended attribute organization, matching pyxattr conventions.
15

16
```python { .api }
17
NS_SECURITY: bytes   # b"security"
18
NS_USER: bytes       # b"user"  
19
NS_SYSTEM: bytes     # b"system"
20
NS_TRUSTED: bytes    # b"trusted"
21
```
22

23
**Usage Examples:**
24

25
```python
26
from xattr import pyxattr_compat
27

28
# Use namespace constants
29
user_ns = pyxattr_compat.NS_USER        # b"user"
30
security_ns = pyxattr_compat.NS_SECURITY  # b"security"
31
```
32

33
### Get Attribute
34

35
Retrieve extended attribute with optional namespace support, matching pyxattr calling conventions.
36

37
```python { .api }
38
def getxattr(item, attribute, nofollow=False):
39
    """
40
    Get extended attribute (pyxattr compatible).
41
    
42
    Parameters:
43
    - item: str/bytes path, int fd, or file-like object
44
    - attribute: str/bytes, attribute name
45
    - nofollow: bool, don't follow symbolic links
46
    
47
    Returns:
48
    bytes: attribute value
49
    
50
    Raises:
51
    IOError: filesystem error or attribute not found
52
    """
53

54
def get(item, name, nofollow=False, namespace=None):
55
    """
56
    Get extended attribute with namespace support.
57
    
58
    Parameters:
59
    - item: str/bytes path, int fd, or file-like object
60
    - name: bytes, attribute name (without namespace prefix)
61
    - nofollow: bool, don't follow symbolic links
62
    - namespace: bytes, namespace prefix (NS_USER, NS_SECURITY, etc.)
63
    
64
    Returns:
65
    bytes: attribute value
66
    
67
    Raises:
68
    IOError: filesystem error or attribute not found
69
    TypeError: namespace is None
70
    """
71
```
72

73
**Usage Examples:**
74

75
```python
76
from xattr import pyxattr_compat
77

78
# Direct attribute access (pyxattr style)
79
value = pyxattr_compat.getxattr('/path/to/file', b'user.description')
80
print(value)  # b'File description'
81

82
# With namespace support
83
value = pyxattr_compat.get('/path/to/file', b'description', 
84
                          namespace=pyxattr_compat.NS_USER)
85
print(value)  # b'File description'
86

87
# Don't follow symlinks
88
link_value = pyxattr_compat.get('/path/to/symlink', b'link_info',
89
                               nofollow=True, namespace=pyxattr_compat.NS_USER)
90
```
91

92
### Set Attribute
93

94
Set extended attribute with flags and namespace support.
95

96
```python { .api }
97
def setxattr(item, name, value, flags=0, nofollow=False):
98
    """
99
    Set extended attribute (pyxattr compatible).
100
    
101
    Parameters:
102
    - item: str/bytes path, int fd, or file-like object
103
    - name: str/bytes, attribute name
104
    - value: bytes, attribute value
105
    - flags: int, operation flags (XATTR_CREATE, XATTR_REPLACE)
106
    - nofollow: bool, don't follow symbolic links
107
    
108
    Raises:
109
    IOError: filesystem error or flag constraints
110
    """
111

112
def set(item, name, value, nofollow=False, flags=0, namespace=None):
113
    """
114
    Set extended attribute with namespace support.
115
    
116
    Parameters:
117
    - item: str/bytes path, int fd, or file-like object
118
    - name: bytes, attribute name (without namespace prefix)
119
    - value: bytes, attribute value
120
    - nofollow: bool, don't follow symbolic links
121
    - flags: int, operation flags (XATTR_CREATE, XATTR_REPLACE)
122
    - namespace: bytes, namespace prefix
123
    
124
    Raises:
125
    IOError: filesystem error or flag constraints
126
    TypeError: namespace is None
127
    """
128
```
129

130
**Usage Examples:**
131

132
```python
133
from xattr import pyxattr_compat
134
import xattr
135

136
# Direct set (pyxattr style)
137
pyxattr_compat.setxattr('/path/to/file', b'user.title', b'My Document')
138

139
# With namespace
140
pyxattr_compat.set('/path/to/file', b'title', b'My Document',
141
                   namespace=pyxattr_compat.NS_USER)
142

143
# With flags
144
pyxattr_compat.set('/path/to/file', b'id', b'12345',
145
                   flags=xattr.XATTR_CREATE,
146
                   namespace=pyxattr_compat.NS_USER)
147

148
# On symlink itself
149
pyxattr_compat.setxattr('/path/to/symlink', b'user.type', b'link', nofollow=True)
150
```
151

152
### List Attributes
153

154
List extended attributes with optional namespace filtering.
155

156
```python { .api }
157
def listxattr(item, nofollow=False):
158
    """
159
    List extended attributes (pyxattr compatible).
160
    
161
    Parameters:
162
    - item: str/bytes path, int fd, or file-like object
163
    - nofollow: bool, don't follow symbolic links
164
    
165
    Returns:
166
    list[bytes]: attribute names as bytes
167
    
168
    Raises:
169
    IOError: filesystem error
170
    """
171

172
def list(item, nofollow=False, namespace=None):
173
    """
174
    List extended attributes with namespace filtering.
175
    
176
    Parameters:
177
    - item: str/bytes path, int fd, or file-like object
178
    - nofollow: bool, don't follow symbolic links
179
    - namespace: bytes/None, namespace to filter by
180
    
181
    Returns:
182
    list[bytes]: attribute names (without namespace prefix if namespace specified)
183
    
184
    Raises:
185
    IOError: filesystem error
186
    """
187
```
188

189
**Usage Examples:**
190

191
```python
192
from xattr import pyxattr_compat
193

194
# List all attributes (returns bytes)
195
attrs = pyxattr_compat.listxattr('/path/to/file')
196
print(attrs)  # [b'user.description', b'user.title']
197

198
# List attributes in specific namespace
199
user_attrs = pyxattr_compat.list('/path/to/file', 
200
                                 namespace=pyxattr_compat.NS_USER)
201
print(user_attrs)  # [b'description', b'title'] (no 'user.' prefix)
202

203
# List all namespaces
204
all_attrs = pyxattr_compat.list('/path/to/file')  # No namespace filtering
205
print(all_attrs)  # [b'user.description', b'user.title', b'security.selinux']
206
```
207

208
### Remove Attribute
209

210
Remove extended attributes with namespace support.
211

212
```python { .api }
213
def removexattr(item, name, nofollow=False):
214
    """
215
    Remove extended attribute (pyxattr compatible).
216
    
217
    Parameters:
218
    - item: str/bytes path, int fd, or file-like object
219
    - name: str/bytes, attribute name
220
    - nofollow: bool, don't follow symbolic links
221
    
222
    Raises:
223
    IOError: filesystem error or attribute not found
224
    """
225

226
def remove(item, name, nofollow=False, namespace=None):
227
    """
228
    Remove extended attribute with namespace support.
229
    
230
    Parameters:
231
    - item: str/bytes path, int fd, or file-like object
232
    - name: bytes, attribute name (without namespace prefix)
233
    - nofollow: bool, don't follow symbolic links
234
    - namespace: bytes, namespace prefix
235
    
236
    Raises:
237
    IOError: filesystem error or attribute not found
238
    TypeError: namespace is None
239
    """
240
```
241

242
**Usage Examples:**
243

244
```python
245
from xattr import pyxattr_compat
246

247
# Remove attribute directly
248
pyxattr_compat.removexattr('/path/to/file', b'user.old_description')
249

250
# Remove with namespace
251
pyxattr_compat.remove('/path/to/file', b'old_description',
252
                      namespace=pyxattr_compat.NS_USER)
253

254
# Remove from symlink
255
pyxattr_compat.remove('/path/to/symlink', b'temp_attr',
256
                      nofollow=True, namespace=pyxattr_compat.NS_USER)
257
```
258

259
### Get All Attributes
260

261
Convenience function to retrieve all attributes and their values, with optional namespace filtering.
262

263
```python { .api }
264
def get_all(item, nofollow=False, namespace=None):
265
    """
266
    Get all extended attributes and their values.
267
    
268
    Parameters:
269
    - item: str/bytes path, int fd, or file-like object
270
    - nofollow: bool, don't follow symbolic links
271
    - namespace: bytes/None, namespace to filter by
272
    
273
    Returns:
274
    list[tuple[bytes, bytes]]: list of (name, value) tuples
275
    
276
    Raises:
277
    IOError: filesystem error
278
    """
279
```
280

281
**Usage Examples:**
282

283
```python
284
from xattr import pyxattr_compat
285

286
# Get all attributes and values
287
all_attrs = pyxattr_compat.get_all('/path/to/file')
288
for name, value in all_attrs:
289
    print(f"{name}: {value}")
290

291
# Get only user namespace attributes
292
user_attrs = pyxattr_compat.get_all('/path/to/file', 
293
                                   namespace=pyxattr_compat.NS_USER)
294
for name, value in user_attrs:
295
    print(f"user.{name}: {value}")  # name doesn't include 'user.' prefix
296
```
297

298
## Migration Example
299

300
Example showing migration from pyxattr to xattr using compatibility layer:
301

302
```python
303
# Original pyxattr code
304
try:
305
    import pyxattr
306
    
307
    # Set attribute
308
    pyxattr.setxattr('/path/to/file', 'user.title', b'Document')
309
    
310
    # Get attribute
311
    title = pyxattr.getxattr('/path/to/file', 'user.title')
312
    
313
    # List attributes
314
    attrs = pyxattr.listxattr('/path/to/file')
315
    
316
except ImportError:
317
    # Fallback to xattr compatibility layer
318
    from xattr import pyxattr_compat as pyxattr
319
    
320
    # Same interface works
321
    pyxattr.setxattr('/path/to/file', b'user.title', b'Document')
322
    title = pyxattr.getxattr('/path/to/file', b'user.title')
323
    attrs = pyxattr.listxattr('/path/to/file')
324
```
325

326
## Key Differences from Main xattr API
327

328
- **Byte strings**: pyxattr compatibility uses bytes for attribute names and values
329
- **Different parameters**: `nofollow` instead of `symlink` parameter (inverted logic)
330
- **Namespace handling**: Built-in namespace prefix handling
331
- **Return types**: Functions return bytes/lists instead of strings where applicable
332
- **Error handling**: Maintains pyxattr exception behavior