doc should generally be writable #91309

pitrou · 2022-03-29T17:32:49Z

BPO	47153
Nosy	@warsaw, @gpshead, @pitrou, @scoder

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2022-03-29.17:32:48.885>
labels = ['interpreter-core', 'type-feature', '3.11']
title = '__doc__ should generally be writable'
updated_at = <Date 2022-04-05.07:27:02.781>
user = 'https://github.com/pitrou'

bugs.python.org fields:

activity = <Date 2022-04-05.07:27:02.781>
actor = 'gregory.p.smith'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Interpreter Core']
creation = <Date 2022-03-29.17:32:48.885>
creator = 'pitrou'
dependencies = []
files = []
hgrepos = []
issue_num = 47153
keywords = []
message_count = 1.0
messages = ['416277']
nosy_count = 4.0
nosy_names = ['barry', 'gregory.p.smith', 'pitrou', 'scoder']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue47153'
versions = ['Python 3.11']

pitrou · 2022-03-29T17:32:49Z

The __doc__ attribute of several object types is not writable: notably descriptors (method/member/getset), as well builtin methods.

This is annoying when wanting to generate docstrings for these objects dynamically. While it's not useful for regular Python code, it comes up when using Cython, which uses these types to implement the methods and properties of "cdef" classes.

rhettinger · 2022-04-25T00:26:24Z

+1

### Rationale for this change Python classes sometimes duplicate docstrings, but change one word such as class name. Add a decorator function as a utility to help deduplicate docstring descriptions. Only works in Python. Does not work in Cython due to this CPython issue python/cpython#91309. ### What changes are included in this PR? Add a decorator `@ doc` that can copy, concatenate, and/or format docstrings between classes. ### Are these changes tested? Tests added. ``` >>> import pyarrow >>> from pyarrow.filesystem import FileSystem, LocalFileSystem, DaskFileSystem, S3FSWrapper >>> from pyarrow.hdfs import HadoopFileSystem >>> for fs in [FileSystem, LocalFileSystem, DaskFileSystem, S3FSWrapper, HadoopFileSystem]: ... print(fs.__name__) ... print(fs.isdir.__doc__) ... FileSystem Return True if path is a directory. Parameters ---------- path : str Path to check. LocalFileSystem Return True if path is a directory. Parameters ---------- path : str Path to check. DaskFileSystem Return True if path is a directory. Parameters ---------- path : str Path to check. S3FSWrapper Return True if path is a directory. Parameters ---------- path : str Path to check. HadoopFileSystem Return True if path is a directory. Parameters ---------- path : str Path to check. ``` Note that `FileSystem.isdir.__doc__` is not dedented because it does not use the `@ doc` decorator. ### Are there any user-facing changes? No * Closes: #34868 Authored-by: Dane Pitkin <dane@voltrondata.com> Signed-off-by: Alenka Frim <frim.alenka@gmail.com>

### Rationale for this change Python classes sometimes duplicate docstrings, but change one word such as class name. Add a decorator function as a utility to help deduplicate docstring descriptions. Only works in Python. Does not work in Cython due to this CPython issue python/cpython#91309. ### What changes are included in this PR? Add a decorator `@ doc` that can copy, concatenate, and/or format docstrings between classes. ### Are these changes tested? Tests added. ``` >>> import pyarrow >>> from pyarrow.filesystem import FileSystem, LocalFileSystem, DaskFileSystem, S3FSWrapper >>> from pyarrow.hdfs import HadoopFileSystem >>> for fs in [FileSystem, LocalFileSystem, DaskFileSystem, S3FSWrapper, HadoopFileSystem]: ... print(fs.__name__) ... print(fs.isdir.__doc__) ... FileSystem Return True if path is a directory. Parameters ---------- path : str Path to check. LocalFileSystem Return True if path is a directory. Parameters ---------- path : str Path to check. DaskFileSystem Return True if path is a directory. Parameters ---------- path : str Path to check. S3FSWrapper Return True if path is a directory. Parameters ---------- path : str Path to check. HadoopFileSystem Return True if path is a directory. Parameters ---------- path : str Path to check. ``` Note that `FileSystem.isdir.__doc__` is not dedented because it does not use the `@ doc` decorator. ### Are there any user-facing changes? No * Closes: apache#34868 Authored-by: Dane Pitkin <dane@voltrondata.com> Signed-off-by: Alenka Frim <frim.alenka@gmail.com>

pitrou added 3.11 bug and security fixes interpreter-core (Objects, Python, Grammar, and Parser dirs) type-feature A feature request or enhancement labels Mar 29, 2022

ezio-melotti transferred this issue from another repository Apr 10, 2022

jorisvandenbossche mentioned this issue Feb 16, 2023

GH-34098: [Python][Docs] Expand dataset method docstrings apache/arrow#34099

Merged

danepitkin mentioned this issue Apr 4, 2023

[Python] Sharing docstrings between classes apache/arrow#34868

Closed

iritkatriel added 3.12 bugs and security fixes and removed 3.11 bug and security fixes labels Apr 4, 2023

danepitkin mentioned this issue Apr 4, 2023

GH-34868: [Python] Share docstrings between classes apache/arrow#34894

Merged

erlend-aasland added 3.13 new features, bugs and security fixes and removed 3.12 bugs and security fixes labels Jan 5, 2024

doc should generally be writable #91309

doc should generally be writable #91309

pitrou commented Mar 29, 2022

pitrou commented Mar 29, 2022

rhettinger commented Apr 25, 2022

__doc__ should generally be writable #91309

__doc__ should generally be writable #91309

Comments

pitrou commented Mar 29, 2022

pitrou commented Mar 29, 2022

rhettinger commented Apr 25, 2022

doc should generally be writable #91309

doc should generally be writable #91309