I often write long docstrings (not sure whether Lisp has its own name
for these). In Python, if the body of a class or function begins with
a string literal, then this becomes the docstring. And a REPL will
display this as help text if you type “help(«object»)”. E.g.
class Matrix :
"representation of a 3-by-2 affine homogeneous matrix. This does not" \
" actually use any Cairo routines to implement its calculations; these" \
" are done entirely using Python numerics. The from_cairo and to_cairo" \
" methods provide conversion to/from cairo_matrix_t structs. Routines" \
" elsewhere expect this Matrix type where the underlying Cairo routine" \
" wants a cairo_matrix_t, and return this type where the Cairo routine" \
" returns a cairo_matrix_t."
...
#end Matrix
This takes advantage of the fact that, like C and some C-derivatives,
Python supports implicit concatenation of adjacent string literals.
This allows me to construct very long string literals without messing
up the layout of my code.
Lisp doesn’t have such an implicit-concatenation convention. But it
has macros. And it easy enough to define a macro which does string concatenation at macro-invocation time, e.g.
(defmacro mstr (&rest strs)
"lets me define a long string literal in pieces across lines, useful for docstrings."
(apply 'concat strs)
) ; defmacro mstr
And using this macro is equally easy:
(defun cur-line (ensure-newline)
(mstr
"returns list of two character positions, representing the"
" beginning and end of the selection if there is one, else"
" the beginning and end of the current line. ensure-newline"
" => ensures there is a newline at the end of the line."
)
...
) ; defun
in python can't you just put the documentation in a string with embedded newlines?
You could just have said
I often write long docstrings (not sure whether Lisp has its own name
for these).
(defmacro mstr (&rest strs)
"lets me define a long string literal in pieces across lines, useful for docstrings."
(apply 'concat strs)
) ; defmacro mstr
And using this macro is equally easy:
(defun cur-line (ensure-newline)
(mstr
"returns list of two character positions, representing the"
" beginning and end of the selection if there is one, else"
" the beginning and end of the current line. ensure-newline"
" => ensures there is a newline at the end of the line."
)
(defmacro mstr () "abc")MSTR
(mstr)"abc"
(defun fn () (mstr) 42)FN
(documentation 'fn 'function)NIL
(defun fn () "abc" 42)FN
(documentation 'fn 'function)"abc"
On 2024-01-18, Lawrence D'Oliveiro <ldo@nz.invalid> wrote:
I often write long docstrings (not sure whether Lisp has its own name
for these).
Lis has its own name: docstrings. It is Python that doesn't have its own name.
On Thu, 18 Jan 2024 15:14:27 +0530, Madhu wrote:
in python can't you just put the documentation in a string with embeddedYou mean triple-quoted strings? And having to add extra blanks at the
newlines?
start of each line, throwing the formatting off?
You could just have saidWhich is why I said “without messing up the layout of my code.”
It's not idiomatic to use python's single-line-restricted "double-quoted string" literals for them. Not made syntactically illegal, but odd.
Common python documentation processors using python docstrings as input
do just expect the bit of excess whitespace that ends up embedded in the docstrings, and generally just trim it away. There's, like, functions in
the stdlib for it
elisp will both complain ...
On Fri, 19 Jan 2024 01:10:54 +0000, David De La Harpe Golden wrote:
It's not idiomatic to use python's single-line-restricted "double-quoted
string" literals for them. Not made syntactically illegal, but odd.
I have no idea why people design a language one way, then expect you to
use it a different way.
Common python documentation processors using python docstrings as input
do just expect the bit of excess whitespace that ends up embedded in the
docstrings, and generally just trim it away. There's, like, functions in
the stdlib for it
I wonder why you need to use them ...
I wonder why you need to use them ...
And why doesn't the Python compiler use them to sanitize the docstring
when the function definition is processed, to spare the tooling from
having to do it.
Compiler now strip indents from docstrings. This will reduce the sizeof bytecode cache (e.g. .pyc file). For example, cache file size for sqlalchemy.orm.session in SQLAlchemy 2.0 is reduced by about 5%. This
On 20/01/2024 00:32, Kaz Kylheku wrote:
Well, sounds like they may well be about to do something like that forI wonder why you need to use them ...
And why doesn't the Python compiler use them to sanitize the docstring
when the function definition is processed, to spare the tooling from
having to do it.
Python 3.13 shortly (at least for compiled files) - pre-release notes -
docs.python.org/3.13/whatsnew/3.13.html
Compiler now strip indents from docstrings. This will reduce the sizeof bytecode cache (e.g. .pyc file). For example, cache file size for sqlalchemy.orm.session in SQLAlchemy 2.0 is reduced by about 5%. This
change will affect tools using docstrings, like doctest.
Not sure about backward compat though, seems like it would necessarily
be quite a breaking change (seeing as docstrings have in fact preserved line-leading whitespace all along, if only to be later typically but not necessarily stripped)
Was debate ongoing 2 weeks ago whether they roll back on the change or not:
github.com/python/cpython/issues/81283#issuecomment-1878628233
Sysop: | Keyop |
---|---|
Location: | Huddersfield, West Yorkshire, UK |
Users: | 418 |
Nodes: | 16 (2 / 14) |
Uptime: | 20:23:35 |
Calls: | 8,804 |
Calls today: | 2 |
Files: | 13,304 |
Messages: | 5,969,801 |