ops.py: cleanup / consistency: remove redundant docstring newline markers

[jayaddison]

Description

Potential (nitpicky) docstring cleanup discovered while preparing #1218.

Checklist

This pull request is:

• A documentation / typographical error fix

[jayaddison]

The docstring here provides a sample case that could be useful for #1218 (in-progress), so I'm going to move this pull request into a draft status too.

[CaselIT]

Hi,

if we change that part we should probably format the text using black.

[CaselIT]

I'm thinking of merging this in https://gerrit.sqlalchemy.org/c/sqlalchemy/alembic/+/4561, so we have a single patch

[jayaddison]

@CaselIT that's OK with me 👍

If you have suggestions for additional ways to provide test coverage for the script, let me know and I'll take a look.

I'm still learning about .pyi stub files (not to mention .pyx that I see elsewhere in the codebase) and this could be a good way to learn more.

[CaselIT]

not to mention .pyx that I see elsewhere in the codebase

these are cython files, and should only be on sqlalchemy side. there is no performance sensitive code on alembic :)

[jayaddison]

Self-replying:

If you have suggestions for additional ways to provide test coverage for the script, let me know and I'll take a look.

Thinking about this more over the past day or so: I suppose the fact that the write_pyi.py script internally runs zimports and black on the output is a kind of self-contained test coverage.

I'm also thinking about going through some of the code samples within docstrings in the codebase to apply black code formatting to those, for consistency in the documentation.

[jayaddison]

I'm also thinking about going through some of the code samples within docstrings in the codebase to apply black code formatting to those, for consistency in the documentation.

Note: doing this could require some care, because there are cases where multiline strings are used within the sample code snippets (in other words: if we're using black format, tripled double-quotes for the code snippets, then the outer docstrings in the source code -- and the write_pyi.py script -- should perhaps use tripled single-quoted strings).

I'm experimenting with this locally to see whether it produces sensible results.

[CaselIT]

by multiline strings you mean a single text that spans multiple python line, but that does not include \n or instead something that's enclosed in ''' to have multiple \n in the text?

[jayaddison]

by multiline strings you mean a single text that spans multiple python line, but that does not include \n or instead something that's enclosed in ''' to have multiple \n in the text?

The second one, I think. For example:

alembic/alembic/autogenerate/api.py

Lines 69 to 79 in d3f869b

	conn.execute(text('''
	create table foo (
	id integer not null primary key,
	old_data varchar,
	x integer
	)'''))
	conn.execute(text('''
	create table bar (
	data varchar
	)'''))

If reformatting those using black formatting, then the double-quotes become single-quotes, and so the outer docstring quotes can be flipped to single-quotes to accommodate that.

[CaselIT]

It's maybe simple in these case to format with black then re-convert """ to ''' so we avoid issues with the doc strings that sometimes are '''