doc/readme.md

   1 # pyxattr
   2
   3 This is the pyxattr module, a Python extension module which gives access
   4 to the extended attributes for filesystem objects available in some
   5 operating systems.
   6
   7 [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/iustin/pyxattr/ci.yml?branch=main)](https://github.com/iustin/pyxattr/actions/workflows/ci.yml)
   8 [![Codecov](https://img.shields.io/codecov/c/github/iustin/pyxattr)](https://codecov.io/gh/iustin/pyxattr)
   9 [![Read the Docs](https://img.shields.io/readthedocs/pyxattr)](https://pyxattr.readthedocs.io/en/latest/?badge=latest)
  10 [![GitHub issues](https://img.shields.io/github/issues/iustin/pyxattr)](https://github.com/iustin/pyxattr/issues)
  11 ![GitHub tag (latest by date)](https://img.shields.io/github/v/tag/iustin/pyxattr)
  12 [![GitHub release (latest by date)](https://img.shields.io/github/v/release/iustin/pyxattr)](https://github.com/iustin/pyxattr/releases)
  13 [![PyPI](https://img.shields.io/pypi/v/pyxattr)](https://pypi.org/project/pyxattr/)
  14 ![Debian package](https://img.shields.io/debian/v/python-pyxattr)
  15 ![Ubuntu package](https://img.shields.io/ubuntu/v/python-pyxattr)
  16 ![GitHub Release Date](https://img.shields.io/github/release-date/iustin/pyxattr)
  17 ![GitHub commits since latest release](https://img.shields.io/github/commits-since/iustin/pyxattr/latest)
  18 ![GitHub last commit](https://img.shields.io/github/last-commit/iustin/pyxattr)
  19 [![OpenSSF Best Practices](https://bestpractices.coreinfrastructure.org/projects/7236/badge)](https://bestpractices.coreinfrastructure.org/projects/7236)
  20
  21 Downloads: go to <https://pyxattr.k1024.org/downloads/>. The source
  22 repository is either at <https://git.k1024.org/pyxattr.git> or at
  23 <https://github.com/iustin/pyxattr>.
  24
  25 See the `CONTRIBUTING.md` file for details on how to contribute.
  26
  27 ## Requirements
  28
  29 The current supported Python versions are 3.7+ (tested up to 3.10), or
  30 PyPy versions 3.7+ (tested up to 3.9). The code should currently be
  31 compatible down to Python 3.4, but such versions are no longer tested.
  32
  33 The library has been written and tested on Linux, kernel v2.4 or
  34 later, with XFS and ext2/ext3/ext4 file systems, and MacOS recent
  35 versions. If any other platform implements the same behaviour,
  36 pyxattr could be used.
  37
  38 To build the module from source, you will need both a Python
  39 development environment/libraries and the C compiler, plus the
  40 setuptools tool installed, and for building the documentation you need
  41 to have Sphinx installed. The exact list of dependencies depends on
  42 the operating system/distribution, but should be something along the
  43 lines of `python3-devel` (RedHat), `python3-all-dev` (Debian), etc.
  44
  45 Alternatively, you can install directly from pip after installing the
  46 above depedencies (C compiler, Python development libraries):
  47
  48     pip install pyxattr
  49
  50 Or you can install already compiled versions from your distribution,
  51 e.g. in Debian:
  52
  53     sudo apt install python3-pyxattr
  54
  55 ## Security
  56
  57 For reporting security vulnerabilities, please see `SECURITY.md`.
  58
  59 ## Basic example
  60
  61     >>> import xattr
  62     >>> xattr.listxattr("file.txt")
  63     ['user.mime_type']
  64     >>> xattr.getxattr("file.txt", "user.mime_type")
  65     'text/plain'
  66     >>> xattr.setxattr("file.txt", "user.comment", "Simple text file")
  67     >>> xattr.listxattr("file.txt")
  68     ['user.mime_type', 'user.comment']
  69     >>> xattr.removexattr ("file.txt", "user.comment")
  70
  71 ## License
  72
  73 pyxattr is Copyright 2002-2008, 2012-2015 Iustin Pop.
  74
  75 pyxattr is free software; you can redistribute it and/or modify it under the
  76 terms of the GNU Lesser General Public License as published by the Free
  77 Software Foundation; either version 2.1 of the License, or (at your option) any
  78 later version. See the COPYING file for the full license terms.
  79
  80 Note that previous versions had different licenses: version 0.3 was licensed
  81 under LGPL version 3 (which, I realized later, is not compatible with GPLv2,
  82 hence the change to LGPL 2.1), and even older versions were licensed under GPL
  83 v2 or later.