From c08a44777d809bbf7ee5e2f33329515e3ddea8b5 Mon Sep 17 00:00:00 2001 From: Iustin Pop Date: Wed, 16 May 2012 00:03:47 +0200 Subject: [PATCH] Switch documentation style to sphinx Still work needed to transition this completely, but looks good so far. --- .gitignore | 3 +- Makefile | 35 ++++++ doc/conf.py | 252 +++++++++++++++++++++++++++++++++++++ doc/index.rst | 17 +++ doc/module.rst | 54 ++++++++ doc/news.rst | 1 + xattr.c | 334 +++++++++++++++++++++++-------------------------- 7 files changed, 521 insertions(+), 175 deletions(-) create mode 100644 Makefile create mode 100644 doc/conf.py create mode 100644 doc/index.rst create mode 100644 doc/module.rst create mode 120000 doc/news.rst diff --git a/.gitignore b/.gitignore index 080bfcd..cf4633f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,8 @@ /MANIFEST /build /dist -/html +/doc/doctrees/ +/doc/html/ /pyxattr.egg-info /test/*.pyc /xattr.html diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..c17dbeb --- /dev/null +++ b/Makefile @@ -0,0 +1,35 @@ +SPHINXOPTS = -W +SPHINXBUILD = sphinx-build +DOCDIR = doc +DOCHTML = $(DOCDIR)/html +DOCTREES = $(DOCDIR)/doctrees +ALLSPHINXOPTS = -d $(DOCTREES) $(SPHINXOPTS) $(DOCDIR) + +MODNAME = xattr.so +RSTFILES = doc/index.rst doc/module.rst NEWS README doc/conf.py + +all: doc test + +$(MODNAME): xattr.c + ./setup.py build_ext --inplace + +$(DOCHTML)/index.html: $(MODNAME) $(RSTFILES) + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DOCHTML) + touch $@ + +doc: $(DOCHTML)/index.html + +test: + for ver in 2.4 2.5 2.6 2.7 3.0 3.1 3.2; do \ + if type python$$ver >/dev/null; then \ + echo Testing with python$$ver; \ + python$$ver ./setup.py test; \ + fi; \ + done + +clean: + rm -rf $(DOCHTML) $(DOCTREES) + rm -f $(MODNAME) + rm -rf build + +.PHONY: doc test clean diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..0031d00 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,252 @@ +# -*- coding: utf-8 -*- +# +# pyxattr documentation build configuration file, created by +# sphinx-quickstart on Sun May 13 01:05:18 2012. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.insert(0, os.path.abspath('../')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'pyxattr' +copyright = u'2002, 2003, 2006, 2008, 2012, Iustin Pop' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.5.1' +# The full version, including alpha/beta/rc tags. +release = '0.5.1' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build', 'html'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +default_domain = 'python' + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +keep_warnings = True + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +#html_static_path = ['_static'] +html_static_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True +html_domain_indices = False + +# If false, no index is generated. +#html_use_index = True +html_use_index = False + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True +html_show_sourcelink = False + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'pyxattrdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'pyxattr.tex', u'pyxattr Documentation', + u'Iustin Pop', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'pyxattr', u'pyxattr Documentation', + [u'Iustin Pop'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'pyxattr', u'pyxattr Documentation', + u'Iustin Pop', 'pyxattr', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +autodoc_member_order = 'alphabetical' diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..336e191 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,17 @@ +====================================== + Welcome to pylibacl's documentation! +====================================== + +.. include:: ../README + :start-line: 2 + +Contents +-------- + +.. toctree:: + :maxdepth: 2 + + module.rst + news.rst + +Also see the :ref:`search`. diff --git a/doc/module.rst b/doc/module.rst new file mode 100644 index 0000000..0231605 --- /dev/null +++ b/doc/module.rst @@ -0,0 +1,54 @@ +Interface to extended filesystem attributes +=========================================== + +.. automodule:: xattr + +Constants +--------- + +.. data:: XATTR_CREATE + + Used as flags value, the target attribute + will be created, giving an error if it already exists. + +.. data:: XATTR_REPLACE + + Used as flags value, the target attribute + will be replaced, giving an error if it doesn't exist. + +.. data:: NS_SECURITY + + The security namespace, used by kernel security modules. + +.. data:: NS_SYSTEM + + The system namespace, used by the kernel to store things such as + ACLs and capabilities. + +.. data:: NS_TRUSTED + + The trusted namespace, visible and accessibly only to trusted + processes, used to implement mechanisms in user space. + +.. data:: NS_USER + + The user namespace; this is the namespace accessible to + non-privileged processes. + +Functions +--------- + +.. autofunction:: list +.. autofunction:: get +.. autofunction:: get_all +.. autofunction:: set +.. autofunction:: remove + + +Deprecated functions +-------------------- + +.. autofunction:: getxattr +.. autofunction:: setxattr +.. autofunction:: listxattr +.. autofunction:: removexattr diff --git a/doc/news.rst b/doc/news.rst new file mode 120000 index 0000000..0fae0f8 --- /dev/null +++ b/doc/news.rst @@ -0,0 +1 @@ +../NEWS \ No newline at end of file diff --git a/xattr.c b/xattr.c index 6a5f4f8..52965e8 100644 --- a/xattr.c +++ b/xattr.c @@ -43,6 +43,50 @@ typedef int Py_ssize_t; #define PyBytes_FromString PyString_FromString #endif +#define ITEM_DOC \ + ":param item: a string representing a file-name, or a file-like\n" \ + " object, or a file descriptor; this represents the file on \n" \ + " which to act\n" + +#define NOFOLLOW_DOC \ + ":param nofollow: if true and if\n" \ + " the file name given is a symbolic link, the\n" \ + " function will operate on the symbolic link itself instead\n" \ + " of its target; defaults to false\n" \ + ":type nofollow: boolean, optional\n" \ + +#define NS_DOC \ + ":param namespace: if given, the attribute must not contain the\n" \ + " namespace, but instead it will be taken from this parameter\n" \ + ":type namespace: bytes\n" + +#define NAME_GET_DOC \ + ":param string name: the attribute whose value to retrieve;\n" \ + " usually in the form of ``system.posix_acl`` or ``user.mime_type``\n" + +#define NAME_SET_DOC \ + ":param string name: the attribute whose value to set;\n" \ + " usually in the form of ``system.posix_acl`` or ``user.mime_type``\n" + +#define NAME_REMOVE_DOC \ + ":param string name: the attribute to remove;\n" \ + " usually in the form of ``system.posix_acl`` or \n" \ + " ``user.mime_type``\n" + +#define VALUE_DOC \ + ":param string value: possibly with embedded NULLs; note that there\n" \ + " are restrictions regarding the size of the value, for\n" \ + " example, for ext2/ext3, maximum size is the block size\n" \ + +#define FLAGS_DOC \ + ":param flags: if 0 or omitted the attribute will be\n" \ + " created or replaced; if :const:`XATTR_CREATE`, the attribute\n" \ + " will be created, giving an error if it already exists;\n" \ + " if :const:`XATTR_REPLACE`, the attribute will be replaced,\n" \ + " giving an error if it doesn't exist;\n" \ + ":type flags: integer\n" + + /* the estimated (startup) attribute buffer size in multi-operations */ #define ESTIMATE_ATTR_SIZE 256 @@ -198,20 +242,16 @@ const char *matches_ns(const char *ns, const char *name) { /* Wrapper for getxattr */ static char __pygetxattr_doc__[] = + "getxattr(item, attribute[, nofollow=False])\n" "Get the value of a given extended attribute (deprecated).\n" "\n" - "Parameters:\n" - " - a string representing filename, or a file-like object,\n" - " or a file descriptor; this represents the file on \n" - " which to act\n" - " - a string, representing the attribute whose value to retrieve;\n" - " usually in form of system.posix_acl or user.mime_type\n" - " - (optional) a boolean value (defaults to false), which, if\n" - " the file name given is a symbolic link, makes the\n" - " function operate on the symbolic link itself instead\n" - " of its target;\n" - "@deprecated: since version 0.4, this function has been deprecated\n" - " by the L{get} function\n" + ITEM_DOC + NAME_GET_DOC + NOFOLLOW_DOC + "\n" + ".. deprecated:: 0.4\n" + " this function has been deprecated\n" + " by the :func:`get` function.\n" ; static PyObject * @@ -268,6 +308,7 @@ pygetxattr(PyObject *self, PyObject *args) /* Wrapper for getxattr */ static char __get_doc__[] = + "get(item, name[, nofollow=False, namespace=None])\n" "Get the value of a given extended attribute.\n" "\n" "Example:\n" @@ -276,23 +317,15 @@ static char __get_doc__[] = " >>> xattr.get('/path/to/file', 'comment', namespace=xattr.NS_USER)\n" " 'test'\n" "\n" - "@param item: the item to query; either a string representing the\n" - " filename, or a file-like object, or a file descriptor\n" - "@param name: the attribute whose value to set; usually in form of\n" - " system.posix_acl or user.mime_type\n" - "@type name: string\n" - "@param nofollow: if given and True, and the function is passed a\n" - " filename that points to a symlink, the function will act on the\n" - " symlink itself instead of its target\n" - "@type nofollow: boolean\n" - "@param namespace: if given, the attribute must not contain the\n" - " namespace itself, but instead the namespace will be taken from\n" - " this parameter\n" - "@type namespace: string\n" - "@return: the value of the extended attribute (can contain NULLs)\n" - "@rtype: string\n" - "@raise EnvironmentError: caused by any system errors\n" - "@since: 0.4\n" + ITEM_DOC + NAME_GET_DOC + NOFOLLOW_DOC + NS_DOC + ":return: the value of the extended attribute (can contain NULLs)\n" + ":rtype: string\n" + ":raises EnvironmentError: caused by any system errors\n" + "\n" + ".. versionadded:: 0.4\n" ; static PyObject * @@ -360,40 +393,39 @@ xattr_get(PyObject *self, PyObject *args, PyObject *keywds) /* Wrapper for getxattr */ static char __get_all_doc__[] = + "get_all(item[, nofollow=False, namespace=None])\n" "Get all the extended attributes of an item.\n" "\n" "This function performs a bulk-get of all extended attribute names\n" "and the corresponding value.\n" "Example:\n" + "\n" " >>> xattr.get_all('/path/to/file')\n" " [('user.mime-type', 'plain/text'), ('user.comment', 'test'),\n" " ('system.posix_acl_access', '\\x02\\x00...')]\n" " >>> xattr.get_all('/path/to/file', namespace=xattr.NS_USER)\n" " [('mime-type', 'plain/text'), ('comment', 'test')]\n" "\n" - "@param item: the item to query; either a string representing the\n" - " filename, or a file-like object, or a file descriptor\n" - "@keyword namespace: an optional namespace for filtering the\n" - " attributes; for example, querying all user attributes can be\n" - " accomplished by passing namespace=L{NS_USER}\n" - "@type namespace: string\n" - "@keyword nofollow: if passed and true, if the target file is a\n" - " symbolic link, the attributes for the link itself will be\n" - " returned, instead of the attributes of the target\n" - "@type nofollow: boolean\n" - "@return: list of tuples (name, value); note that if a namespace\n" - " argument was passed, it (and the separator) will be stripped from\n" - " the names returned\n" - "@rtype: list\n" - "@raise EnvironmentError: caused by any system errors\n" - "@note: Since reading the whole attribute list is not an atomic\n" - " operation, it might be possible that attributes are added\n" - " or removed between the initial query and the actual reading\n" - " of the attributes; the returned list will contain only the\n" - " attributes that were present at the initial listing of the\n" - " attribute names and that were still present when the read\n" - " attempt for the value is made.\n" - "@since: 0.4\n" + ITEM_DOC + ":keyword namespace: an optional namespace for filtering the\n" + " attributes; for example, querying all user attributes can be\n" + " accomplished by passing namespace=:const:`NS_USER`\n" + ":type namespace: string\n" + NOFOLLOW_DOC + ":return: list of tuples (name, value); note that if a namespace\n" + " argument was passed, it (and the separator) will be stripped from\n" + " the names returned\n" + ":rtype: list\n" + ":raises EnvironmentError: caused by any system errors\n" + "\n" + ".. note:: Since reading the whole attribute list is not an atomic\n" + " operation, it might be possible that attributes are added\n" + " or removed between the initial query and the actual reading\n" + " of the attributes; the returned list will contain only the\n" + " attributes that were present at the initial listing of the\n" + " attribute names and that were still present when the read\n" + " attempt for the value is made.\n" + ".. versionadded:: 0.4\n" ; static PyObject * @@ -525,6 +557,7 @@ get_all(PyObject *self, PyObject *args, PyObject *keywds) static char __pysetxattr_doc__[] = + "setxattr(item, name, value[, flags=0, nofollow=False])\n" "Set the value of a given extended attribute (deprecated).\n" "\n" "Be careful in case you want to set attributes on symbolic\n" @@ -532,26 +565,15 @@ static char __pysetxattr_doc__[] = "flags value if you want the default behaviour (create or " "replace)\n" "\n" - "Parameters:\n" - " - a string representing a file-name, or a file-like object,\n" - " or a file descriptor; this represents the file on \n" - " which to act\n" - " - a string, representing the attribute whose value to set;\n" - " usually in form of system.posix_acl or user.mime_type\n" - " - a string, possibly with embedded NULLs; note that there\n" - " are restrictions regarding the size of the value, for\n" - " example, for ext2/ext3, maximum size is the block size\n" - " - (optional) flags; if 0 or omitted the attribute will be \n" - " created or replaced; if XATTR_CREATE, the attribute \n" - " will be created, giving an error if it already exists;\n" - " of XATTR_REPLACE, the attribute will be replaced,\n" - " giving an error if it doesn't exists;\n" - " - (optional) a boolean value (defaults to false), which, if\n" - " the file name given is a symbolic link, makes the\n" - " function operate on the symbolic link itself instead\n" - " of its target;\n" - "@deprecated: since version 0.4, this function has been deprecated\n" - " by the L{set} function\n" + ITEM_DOC + NAME_SET_DOC + VALUE_DOC + FLAGS_DOC + NOFOLLOW_DOC + "\n" + ".. deprecated:: 0.4\n" + " this function has been deprecated\n" + " by the :func:`set` function.\n" ; /* Wrapper for setxattr */ @@ -598,39 +620,25 @@ pysetxattr(PyObject *self, PyObject *args) } static char __set_doc__[] = + "set(item, name, value[, flags=0, namespace=None])\n" "Set the value of a given extended attribute.\n" "\n" "Example:\n" + "\n" " >>> xattr.set('/path/to/file', 'user.comment', 'test')\n" " >>> xattr.set('/path/to/file', 'comment', 'test'," " namespace=xattr.NS_USER)\n" "\n" - "@param item: the item to query; either a string representing the\n" - " filename, or a file-like object, or a file descriptor\n" - "@param name: the attribute whose value to set; usually in form of\n" - " system.posix_acl or user.mime_type\n" - "@type name: string\n" - "@param value: a string, possibly with embedded NULLs; note that there\n" - " are restrictions regarding the size of the value, for\n" - " example, for ext2/ext3, maximum size is the block size\n" - "@type value: string\n" - "@param flags: if 0 or ommited the attribute will be\n" - " created or replaced; if L{XATTR_CREATE}, the attribute\n" - " will be created, giving an error if it already exists;\n" - " if L{XATTR_REPLACE}, the attribute will be replaced,\n" - " giving an error if it doesn't exists;\n" - "@type flags: integer\n" - "@param nofollow: if given and True, and the function is passed a\n" - " filename that points to a symlink, the function will act on the\n" - " symlink itself instead of its target\n" - "@type nofollow: boolean\n" - "@param namespace: if given, the attribute must not contain the\n" - " namespace itself, but instead the namespace will be taken from\n" - " this parameter\n" - "@type namespace: string\n" - "@rtype: None\n" - "@raise EnvironmentError: caused by any system errors\n" - "@since: 0.4\n" + ITEM_DOC + NAME_SET_DOC + VALUE_DOC + FLAGS_DOC + NOFOLLOW_DOC + NS_DOC + ":returns: None\n" + ":raises EnvironmentError: caused by any system errors\n" + "\n" + ".. versionadded:: 0.4\n" ; /* Wrapper for setxattr */ @@ -691,21 +699,15 @@ xattr_set(PyObject *self, PyObject *args, PyObject *keywds) static char __pyremovexattr_doc__[] = + "removexattr(item, name[, nofollow])\n" "Remove an attribute from a file (deprecated).\n" "\n" - "Parameters:\n" - " - a string representing a file-name, or a file-like object,\n" - " or a file descriptor; this represents the file on \n" - " which to act\n" - " - a string, representing the attribute to be removed;\n" - " usually in form of system.posix_acl or user.mime_type\n" - " - (optional) a boolean value (defaults to false), which, if\n" - " the file name given is a symbolic link, makes the\n" - " function operate on the symbolic link itself instead\n" - " of its target;\n" - "@deprecated: since version 0.4, this function has been deprecated\n" - " by the L{remove}" - " function\n" + ITEM_DOC + NAME_REMOVE_DOC + NOFOLLOW_DOC + "\n" + ".. deprecated:: 0.4\n" + " this function has been deprecated by the :func:`remove` function.\n" ; /* Wrapper for removexattr */ @@ -748,27 +750,21 @@ pyremovexattr(PyObject *self, PyObject *args) } static char __remove_doc__[] = + "remove(item, name[, nofollow=False, namespace=None])\n" "Remove an attribute from a file.\n" "\n" "Example:\n" + "\n" " >>> xattr.remove('/path/to/file', 'user.comment')\n" "\n" - "@param item: the item to query; either a string representing the\n" - " filename, or a file-like object, or a file descriptor\n" - "@param name: the attribute whose value to set; usually in form of\n" - " system.posix_acl or user.mime_type\n" - "@type name: string\n" - "@param nofollow: if given and True, and the function is passed a\n" - " filename that points to a symlink, the function will act on the\n" - " symlink itself instead of its target\n" - "@type nofollow: boolean\n" - "@param namespace: if given, the attribute must not contain the\n" - " namespace itself, but instead the namespace will be taken from\n" - " this parameter\n" - "@type namespace: string\n" - "@since: 0.4\n" - "@rtype: None\n" - "@raise EnvironmentError: caused by any system errors\n" + ITEM_DOC + NAME_REMOVE_DOC + NOFOLLOW_DOC + NS_DOC + ":returns: None\n" + ":raises EnvironmentError: caused by any system errors\n" + "\n" + ".. versionadded:: 0.4\n" ; /* Wrapper for removexattr */ @@ -822,19 +818,14 @@ xattr_remove(PyObject *self, PyObject *args, PyObject *keywds) } static char __pylistxattr_doc__[] = + "listxattr(item[, nofollow=False])\n" "Return the list of attribute names for a file (deprecated).\n" "\n" - "Parameters:\n" - " - a string representing filename, or a file-like object,\n" - " or a file descriptor; this represents the file to \n" - " be queried\n" - " - (optional) a boolean value (defaults to false), which, if\n" - " the file name given is a symbolic link, makes the\n" - " function operate on the symbolic link itself instead\n" - " of its target;\n" - "@deprecated: since version 0.4, this function has been deprecated\n" - " by the L{list}" - " function\n" + ITEM_DOC + NOFOLLOW_DOC + "\n" + ".. deprecated:: 0.4\n" + " this function has been deprecated by the :func:`list` function.\n" ; /* Wrapper for listxattr */ @@ -908,30 +899,27 @@ pylistxattr(PyObject *self, PyObject *args) } static char __list_doc__[] = + "list(item[, nofollow=False, namespace=None])\n" "Return the list of attribute names for a file.\n" "\n" "Example:\n" + "\n" " >>> xattr.list('/path/to/file')\n" " ['user.test', 'user.comment', 'system.posix_acl_access']\n" " >>> xattr.list('/path/to/file', namespace=xattr.NS_USER)\n" " ['test', 'comment']\n" "\n" - "@param item: the item to query; either a string representing the\n" - " filename, or a file-like object, or a file descriptor\n" - "@param nofollow: if given and True, and the function is passed a\n" - " filename that points to a symlink, the function will act on the\n" - " symlink itself instead of its target\n" - "@type nofollow: boolean\n" - "@param namespace: if given, the attribute must not contain the\n" - " namespace itself, but instead the namespace will be taken from\n" - " this parameter\n" - "@type namespace: string\n" - "@return: list of strings; note that if a namespace argument was\n" - " passed, it (and the separator) will be stripped from the names\n" + ITEM_DOC + NOFOLLOW_DOC + NS_DOC + ":returns: the list of attributes; note that if a namespace \n" + " argument was passed, it (and the separator) will be stripped\n" + " from the names\n" " returned\n" - "@rtype: list\n" - "@raise EnvironmentError: caused by any system errors\n" - "@since: 0.4\n" + ":rtype: list\n" + ":raises EnvironmentError: caused by any system errors\n" + "\n" + ".. versionadded:: 0.4\n" ; /* Wrapper for listxattr */ @@ -1032,16 +1020,16 @@ static PyMethodDef xattr_methods[] = { }; static char __xattr_doc__[] = \ - "Interface to extended filesystem attributes.\n" - "\n" "This module gives access to the extended attributes present\n" "in some operating systems/filesystems. You can list attributes,\n" "get, set and remove them.\n" "\n" "The module exposes two sets of functions:\n" - " - the 'old' L{listxattr}, L{getxattr}, L{setxattr}, L{removexattr}\n" + " - the 'old' :func:`listxattr`, :func:`getxattr`, :func:`setxattr`,\n" + " :func:`removexattr`\n" " functions which are deprecated since version 0.4\n" - " - the new L{list}, L{get}, L{get_all}, L{set}, L{remove} functions\n" + " - the new :func:`list`, :func:`get`, :func:`get_all`, :func:`set`,\n" + " :func:`remove` functions\n" " which expose a namespace-aware API and simplify a bit the calling\n" " model by using keyword arguments\n" "\n" @@ -1057,23 +1045,21 @@ static char __xattr_doc__[] = \ " ['user.mime_type', 'user.comment']\n" " >>> xattr.removexattr (\"file.txt\", \"user.comment\")\n" "\n" - "@note: Most or all errors reported by the system while using the xattr\n" - "library will be reported by raising a L{EnvironmentError}; under Linux,\n" - "the following C{errno} values are used:\n" - " - C{ENOATTR} and C{ENODATA} mean that the attribute name is invalid\n" - " - C{ENOTSUP} and C{EOPNOTSUPP} mean that the filesystem does not\n" - " support extended attributes, or that the namespace is invalid\n" - " - C{E2BIG} mean that the attribute value is too big\n" - " - C{ERANGE} mean that the attribute name is too big (it might also\n" - " mean an error in the xattr module itself)\n" - " - C{ENOSPC} and C{EDQUOT} are documented as meaning out of disk space\n" - " or out of disk space because of quota limits\n" + ".. note:: Most or all errors reported by the system while using\n" + " the ``xattr`` library will be reported by raising\n" + " a :exc:`EnvironmentError`; under\n" + " Linux, the following ``errno`` values are used:\n" + "\n" + " - ``ENOATTR`` and ``ENODATA`` mean that the attribute name is\n" + " invalid\n" + " - ``ENOTSUP`` and ``EOPNOTSUPP`` mean that the filesystem does not\n" + " support extended attributes, or that the namespace is invalid\n" + " - ``E2BIG`` mean that the attribute value is too big\n" + " - ``ERANGE`` mean that the attribute name is too big (it might also\n" + " mean an error in the xattr module itself)\n" + " - ``ENOSPC`` and ``EDQUOT`` are documented as meaning out of disk\n" + " space or out of disk space because of quota limits\n" "\n" - "@group Deprecated API: *xattr\n" - "@group Namespace constants: NS_*\n" - "@group set function flags: XATTR_CREATE, XATTR_REPLACE\n" - "@sort: list, get, get_all, set, remove, listxattr, getxattr, setxattr\n" - " removexattr\n" ; #ifdef IS_PY3K @@ -1114,7 +1100,7 @@ initxattr(void) PyModule_AddStringConstant(m, "__version__", _XATTR_VERSION); PyModule_AddStringConstant(m, "__license__", "GNU Lesser General Public License (LGPL)"); - PyModule_AddStringConstant(m, "__docformat__", "epytext en"); + PyModule_AddStringConstant(m, "__docformat__", "restructuredtext en"); PyModule_AddIntConstant(m, "XATTR_CREATE", XATTR_CREATE); PyModule_AddIntConstant(m, "XATTR_REPLACE", XATTR_REPLACE); -- 2.39.5