Manual talk:Pywikibot/Development/Guidelines

Stop using "Robot"?

I am in favor of using "bot" instead of "robot" in messages mainly because it's shorter, but is this already a standard or a change proposed to be a standard? I see more than 1,000 instances of "Robot:" (some of which are not English though) in i18n. whym (talk) 23:24, 23 May 2014 (UTC)

I fixed all of "robot" usage in documentation [1] but in edit summaries there is no need to change it in languages except English, e.g. it's quite common in Dutch to call bot "robot" and in Persian they call "robot" instead of bot and they don't have any word for it. Ladsgroup (talk) 05:05, 24 May 2014 (UTC)

@Ladsgroup: yes, I would exclude non-English messages and "1,000" is an overestimation. I just wanted to note that some English summaries still contain "Robot". [2][3] whym (talk) 05:35, 24 May 2014 (UTC)

Please see gerrit:135183. whym (talk) 05:45, 24 May 2014 (UTC)

Single or double quotes?

I am still finding adjoining lines using different styles. --Ricordisamoa 01:24, 24 May 2014 (UTC)

Good question. I checked the internet and it seems there is no standard about it and people are debating and majority are in favor of double quotes. some interesting links:

• http://stackoverflow.com/questions/56011/single-quotes-vs-double-quotes-in-python
• http://henry.precheur.org/python/python_quote (this is quite interesting and personally I think the writer is right)
• even a question in quora

But for adjoining line I think " is better but what I'm saying is completely personal and it's no standard.
Best Ladsgroup (talk) 05:05, 24 May 2014 (UTC)

I think either is fine. I personally use " by default and ' if there's an " in the string, but I have also caught myself using ' on one line, then " on the other. I'm fine with explicitly preferring either, but I'm also fine with not explicitly stating either. Valhallasw (talk) 21:51, 8 June 2014 (UTC)

xZise and I essentially agreed that we would follow http://henry.precheur.org/python/python_quote in principle during code reviews to be consistent.

The result of ~1.5 years of that rule is we've mostly migrated to single quotes, especially if we remove the basely touched transliteration and date modules, and the tests, and the scripts. These regex are not perfect, but do show roughly that single quotes is four times more common than double quotes.

  $ git grep '^[^"'\'']*'\' -- '*.py' | wc -l
  23929

  $ git grep '^[^"'\'']*"[^"]' -- '*.py' | wc -l
  6756
  $ git grep '^[^"'\'']*"[^"]' -- '*.py' | egrep -v '((transliteration|date)\.py|tests\/)' | wc -l
  2528
  $ git grep '^[^"'\'']*"[^"]' -- '*.py' | egrep -v '((transliteration|date)\.py|(scripts|tests)\/)' | wc -l
  1518

IMO the high percentage of single quotes means we should require it for all new code. There are tasks to move transliteration to an external package, and a patch pending which would switch the quotation mark for almost everything in site.py, and probably other patches which will address many other double quotes. My guess is another year of normal development will see the task almost complete, and we could then do a final switch for any remaining double quotes (which dont contain single quotes).

fwiw, https://pypi.python.org/pypi/flake8-quotes defaults to single quotes. John Vandenberg (talk) 15:48, 7 March 2016 (UTC)

String formatting

The framework uses the % operator, but the official Python 2 documentation says that str.format «is the new standard in Python 3, and should be preferred to the % formatting». --Ricordisamoa 09:18, 25 May 2014 (UTC)

Because we need to move towards python 3 compatibility, I'm in favor of adding this (and fixing it in codes slowly), but at first we need to check utf-8 compatibility Ladsgroup (talk) 09:31, 2 June 2014 (UTC)

The '%' formatting is still usable in Py3k. The .format() method does have slightly better readability ("{abc}" instead of "%(abc)s", and you can do "{page.title}" inline). I'm not sure what Amir means with 'utf-8 compatibility' - the formatting methods are equivalent in the aspect of unicode. Valhallasw (talk) 21:50, 8 June 2014 (UTC)

I find that using str.format causes longer lines that need to be split. As a result, we need to also provide recommendations on how to split. I am quite liking the style

 'a {0}'
 .format('b')

I am not very keen on

 'a {0}'.format(
     'b')

John Vandenberg (talk) 16:41, 7 March 2016 (UTC)

format is a method of a string object. Like other object methods the usual syntax is object.funcname(). This syntax should not be disrupted for string constants but should follow other string methods like strip() or split() etc. imho the only way might be

  'a {0}'
  ''.format('b')

which does follow the usual syntax.  @xqt 09:01, 8 March 2016 (UTC)

Yea, that is not a bad option. I could get used to it. John Vandenberg (talk) 09:08, 8 March 2016 (UTC)

The "should be preferred to the % formatting" clause has been removed from the documentation of Python 3.3+. In Python 3.5 they even added % formatting for byte-strings and bytearrays. It's not going to be deprecated and it's not even prefered anymore. I'm in favor of removing the current preference for string.format. Dalba 15:13, 14 December 2017 (UTC)

In 3.8 release doc modulo formatting is still noted as "old string formatting" [4] and also refer https://docs.python.org/3.8/library/stdtypes.html#old-string-formatting with that note:

The formatting operations described here exhibit a variety of quirks that lead to a number of common errors (such as failing to display tuples and dictionaries correctly). Using the newer formatted string literals, the str.format() interface, or template strings may help avoid these errors

 @xqt 09:36, 28 September 2018 (UTC)

[DROP]/[drop]/[REMOVE]/[remove] when dropping/removing no longer supported feature/code?

I'm proposing a prefix for when code, a feature, functionality, support for something etc is being removed from PWB. For example, see change: https://gerrit.wikimedia.org/r/c/pywikibot/core/+/508717. Can we use such a prefix when making changes related to this? If so, which one is better;

• [remove]
• [REMOVE]
• [drop]
• [DROP]

If we agree on such a prefix, we can add it to Manual:Pywikibot/Development/Guidelines#Making_a_patch, thanks. Cc User:Ladsgroup, User:Xqt, User:Dvorapa, User:Framawiki. --X-Savitar (talk) 14:01, 10 June 2019 (UTC)

I think it'll be more convenient to just switch to https://www.conventionalcommits.org style. There are some tools already available for it, no need to reinvent the wheel. For example https://github.com/woile/commitizen can generate standard commit messages interactively. https://github.com/Michael-F-Bryan/auto-changelog is able to update the change log according to git commit messages. And if pywikibot starts to use true semantic versioning some day, https://github.com/relekang/python-semantic-release can help in the release process as well. (Disclaimer: I have not used these tools myself, more investigation is needed in case pywikibot decides to adapt them.)

Dalba 06:42, 14 June 2019 (UTC)