bug#11899: 24.1.50; Weird names and unhelpful docstrings for some python function

bug#11899: 24.1.50; Weird names and unhelpful docstrings for some python function

[Ivan Andrus]

The functions

  python-nav-sentence-start
  python-nav-sentence-end
  python-nav-forward-sentence
  python-nav-backward-sentence

have weird names in the sense that they don't move by sentences.  In
fact the concept of a sentence in python doesn't even make sense.  I
have no problem with them being bound to forward-sentence and
backward-sentence--in fact I do similar things in other modes, but at
least the docstrings (if not the names) should explain that they move by
statements instead of sentences (if that is in fact what they do).

Perhaps they should also be aliased to

  python-beginning-of-statement
  python-end-of-statement

if the semantics match, since those functions are now gone.

-Ivan

P.S. Is this the right place to file a bug against the new
python.el, or should I file it on github?




In GNU Emacs 24.1.50.1 (i386-apple-darwin10.8.0, NS apple-appkit-1038.36)
of 2012-07-10 on oroszlan.local
Bzr revision: 108995 rgm@gnu.org-20120710101729-d50lf86lytae0ts2
Windowing system distributor `Apple', version 10.3.1038
Configured using:
`configure '--with-ns''

Important settings:
  locale-coding-system: nil
  default enable-multibyte-characters: t

Major mode: SAGE

Minor modes in effect:
  diff-auto-refine-mode: t
  TeX-PDF-mode: t
  highlight-symbol-mode: t
  hi-lock-mode: t
  which-function-mode: t
  show-paren-mode: t
  recentf-mode: t
  msb-mode: t
  minibuffer-depth-indicate-mode: t
  global-hl-line-mode: t
  delete-selection-mode: t
  auto-image-file-mode: t
  auto-insert-mode: t
  yas/global-mode: t
  yas/minor-mode: t
  shell-dirtrack-mode: t
  ido-everywhere: t
  global-visible-mark-mode: t
  visible-mark-mode: t
  gvol-mode: t
  desktop-save-mode: t
  drag-stuff-global-mode: t
  drag-stuff-mode: t
  command-frequency-autosave-mode: t
  command-frequency-mode: t
  tooltip-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  column-number-mode: t
  line-number-mode: t
  transient-mark-mode: t

Recent input:
C-c C-f C-x C-f p y r e <return> SPC C-t C-c C-f C-;
C-c C-f <C-tab> q TAB <C-tab> TAB TAB TAB TAB TAB TAB
C-1 M-( TAB C-y C-M-SPC C-M-j C-1 M-( C-l w h e n SPC
, , n o t SPC , , f b o u n d p C-o C-M-u <return>
C-o C-M-l C-M-j C-M-k C-/ TAB C-e C-e C-\ ' C-y C-k
TAB C-l C-x C-e C-l C-x C-e C-M-SPC C-M-l <tab> C-e
<return> C-x C-e C-M-j TAB TAB TAB C-e C-M-j <return>
TAB <C-S-backspace> C-k <C-S-backspace> <up> <M-down>
<M-down> <M-down> <M-down> <M-down> <M-down> <M-down>
<M-down> <M-down> <M-down> <tab> C-k C-d C-e C-SPC
<down> <tab> <down> <down> <tab> <up> <up> <up> <up>
TAB TAB C-x C-s C-k C-k <C-f3> C-a C-M-k , , w h e
n SPC , , n o t SPC , , f b o u n d p SPC ' C-y C-M-o
C-M-o <return> , , d e f u n SPC C-y SPC , , C-M-o
<return> C-M-o <return> <down> <f3> <f3> <f3> <f3>
<f3> C-x C-s C-h f p y t h <tab> n a <tab> <tab> s
e <tab> s t <tab> <return> <C-tab> <down> <right> <return>
<C-tab> <C-tab> <C-tab> C-k C-k C-M-k C-h f C-g M-w
C-x b l i b g a p . C-g C-x C-f <backspace> <backspace>
<backspace> <return> l i b C-s <return> C-k C-k C-k
C-k C-k C-k C-k C-k C-k C-k C-k C-k C-k C-k C-k C-k
C-k C-k C-k M-x p y t h <tab> - m <backspace> n a <tab>
f o <return> M-x <return> M-x <return> M-x <return>
M-x <return> M-x <return> M-x <return> M-x <return>
M-x <return> M-x <return> M-x e m C-g M-x e m a c s
b u g <return>

Recent messages:
Error during redisplay: (wrong-type-argument arrayp nil) [3 times]
/Users/gvol/.emacs-uptimes
byte-code: Buffer is read-only: #<buffer *Help*>
Quit
QuitError during redisplay: (wrong-type-argument arrayp nil)
Error during redisplay: (wrong-type-argument arrayp nil) [63 times]
eval: QuitError during redisplay: (wrong-type-argument arrayp nil)
Error during redisplay: (wrong-type-argument arrayp nil) [3 times]
Scanning for dabbrevs...done
Error during redisplay: (wrong-type-argument arrayp nil) [11 times]

Load-path shadows:
/Users/gvol/.emacs.d/elpa/parenface-20091203/parenface hides ~/.emacs.d/local/parenface
/Users/gvol/.emacs.d/elpa/hl-sexp-1.0.0/hl-sexp hides ~/.emacs.d/local/hl-sexp
/Users/gvol/.emacs.d/elpa/python-mode-6.0.3/highlight-indentation hides ~/.emacs.d/local/highlight-indentation
/Users/gvol/.emacs.d/elpa/command-frequency-1.1/command-frequency hides ~/.emacs.d/local/command-frequency
/Users/gvol/vcs/sage-mode/emacs/.dir-locals hides /Users/gvol/vcs/emacs/local/nextstep/Emacs.app/Contents/Resources/lisp/gnus/.dir-locals
~/.emacs.d/local/lisp-mnt hides /Users/gvol/vcs/emacs/local/nextstep/Emacs.app/Contents/Resources/lisp/emacs-lisp/lisp-mnt

Features:
(shadow sort mail-extr emacsbug message rfc822 mml mml-sec mm-decode
mm-bodies mm-encode mail-parse rfc2231 mailabbrev gmm-utils mailheader
sendmail rfc2047 rfc2045 ietf-drums mail-utils esh-var esh-io esh-cmd
esh-ext esh-proc esh-arg esh-groups eshell esh-module esh-mode esh-util
hippie-exp lisp-mnt checkdoc elint debug pyrex multi-isearch ffap
url-parse url-vars dabbrev smerge-mode diff-mode sage-view parse-time
vc-cvs sgml-mode preview prv-emacs adaptive-wrap tex-fold reftex-vcr
reftex-dcr reftex-auc reftex reftex-vars tex-bar tex-buf toolbar-x
font-latex latex tex-style sage-auctex tex subword sage-mode hideshow
python org-colview vc-svn compile sh-script smie executable tabify
cal-iso org-mobile reveal org-habit org-wl org-w3m org-vm org-rmail
org-mhe org-mew org-irc org-jsinfo org-infojs org-html org-exp ob-exp
org-exp-blocks find-func org-agenda org-info org-gnus org-docview
org-bibtex bibtex org-bbdb org-archive org-id org-crypt ob-python org
ob-emacs-lisp ob-tangle ob-ref ob-lob ob-table org-footnote org-src
ob-comint ob-keys ob ob-eval org-pcomplete org-list org-faces org-compat
org-entities org-macs noutline outline gvol-light-theme elide-head
vc-bzr vc-hg eldoc highlight-parentheses greedy-delete highlight-symbol
hi-lock thingatpt time jka-compr saveplace uniquify which-func imenu
paren recentf tree-widget wid-edit msb mb-depth icomplete hl-line delsel
image-file cus-start cus-load diary-lib diary-loaddefs cal-menu calendar
cal-loaddefs warnings autoinsert yasnippet dropdown-list derived cl-macs
gv help-mode view tramp tramp-compat auth-source eieio byte-opt bytecomp
byte-compile cconv gnus-util mm-util mail-prsvr password-cache
tramp-loaddefs shell pcomplete comint ansi-color format-spec smex ido
visible-mark parenface fold cl cl-lib macroexp commit-patch-buffer
log-edit ring pcvs-util add-log vc ediff vc-dispatcher sage rx sage-load
xml desktop drag-stuff browse-kill-ring backtr command-frequency uptimes
pp server easy-mmode assoc dired+ edmacro kmacro dired-x ediff-merg
ediff-diff ediff-wind ediff-mult ediff-help ediff-init ediff-util
dired-aux dired windmove ac-slime-autoloads adaptive-wrap-autoloads
applescript-mode-autoloads auctex-autoloads tex-site info easymenu
browse-kill-ring-autoloads buffer-move-autoloads c-eldoc-autoloads
columnify-autoloads command-frequency-autoloads company-autoloads
drag-stuff-autoloads durendal-autoloads emstar-autoloads
feature-mode-autoloads goto-last-change-autoloads
graphviz-dot-mode-autoloads highlight-parentheses-autoloads
highlight-symbol-autoloads hl-sexp-autoloads keyfreq-autoloads
finder-inf markdown-mode+-autoloads markdown-mode-autoloads
paredit-autoloads parenface-autoloads python-mode-autoloads
redo+-autoloads rw-hunspell-autoloads scpaste-autoloads
htmlize-autoloads scss-mode-autoloads slime-clj-autoloads
slime-fuzzy-autoloads slime-ritz-autoloads smex-autoloads
speck-autoloads swank-clojure-autoloads advice help-fns advice-preload
clojure-mode-autoloads slime-repl-autoloads slime-autoloads
xml-rpc-autoloads package time-date tooltip ediff-hook vc-hooks
lisp-float-type mwheel ns-win tool-bar dnd fontset image regexp-opt
fringe tabulated-list newcomment lisp-mode register page menu-bar
rfn-eshadow timer select scroll-bar mouse jit-lock font-lock syntax
facemenu font-core frame cham georgian utf-8-lang misc-lang vietnamese
tibetan thai tai-viet lao korean japanese hebrew greek romanian slovak
czech european ethiopic indian cyrillic chinese case-table epa-hook
jka-cmpr-hook help simple abbrev minibuffer loaddefs button faces
cus-face files text-properties overlay sha1 md5 base64 format env
code-pages mule custom widget hashtable-print-readable backquote
make-network-process ns multi-tty emacs)

bug#11899: 24.1.50; Weird names and unhelpful docstrings for some python function

[Stefan Monnier]

>   python-nav-sentence-start
>   python-nav-sentence-end
>   python-nav-forward-sentence
>   python-nav-backward-sentence
> have weird names in the sense that they don't move by sentences.

Indeed, thanks for catching that.  Fabián, can you take a look at it?

> P.S. Is this the right place to file a bug against the new python.el,

Yes, thank you,


        Stefan

bug#11899: 24.1.50; Weird names and unhelpful docstrings for some python function

[Fabián Ezequiel Gallina]

On 07/10/2012 07:23 PM, Stefan Monnier wrote:
>>    python-nav-sentence-start
>>    python-nav-sentence-end
>>    python-nav-forward-sentence
>>    python-nav-backward-sentence
>> have weird names in the sense that they don't move by sentences.

Can you give me an example of what do you expect and the current 
behavior so I can have a more specific example to work on? A simplified 
python file and short explanation would be enough.

> Indeed, thanks for catching that.  Fabián, can you take a look at it?
>
>> P.S. Is this the right place to file a bug against the new python.el,
> Yes, thank you,
>
>
>          Stefan

Regards,

-- 
Fabián E. Gallina
Co-Founder of Anue
Skype: caffeineGalli
http://www.anue.biz/

bug#11899: 24.1.50; Weird names and unhelpful docstrings for some python function

[Ivan Andrus]

On Jul 11, 2012, at 3:14 AM, Fabián Ezequiel Gallina wrote:
> On 07/10/2012 07:23 PM, Stefan Monnier wrote:
>>>   python-nav-sentence-start
>>>   python-nav-sentence-end
>>>   python-nav-forward-sentence
>>>   python-nav-backward-sentence
>>> have weird names in the sense that they don't move by sentences.
> 
> Can you give me an example of what do you expect and the current behavior so I can have a more specific example to work on? A simplified python file and short explanation would be enough.

I'm not complaining about the functionality here.  I just don't know what a "sentence" means in a python file.  I think what is meant is a python statement, but the docstrings should reflect that, or define what is meant by a sentence.

That said, I did just notice that M-a (python-nav-backward-sentence) gets "stuck" on the comment in the test below.  If I put a blank line after the comment then it doesn't.

print libgap('if 4>3 then\nprint("hi");\nfi')
# Abort/segfault
print libgap('SmallGroup(12,3)')

I can create a new bug for that if desired.

-Ivan

bug#11899: 24.1.50; Weird names and unhelpful docstrings for some python function

[Fabián Ezequiel Gallina]

On 07/11/2012 09:42 AM, Ivan Andrus wrote:
> On Jul 11, 2012, at 3:14 AM, Fabián Ezequiel Gallina wrote:
>> On 07/10/2012 07:23 PM, Stefan Monnier wrote:
>>>>    python-nav-sentence-start
>>>>    python-nav-sentence-end
>>>>    python-nav-forward-sentence
>>>>    python-nav-backward-sentence
>>>> have weird names in the sense that they don't move by sentences.
>> Can you give me an example of what do you expect and the current behavior so I can have a more specific example to work on? A simplified python file and short explanation would be enough.
> I'm not complaining about the functionality here.  I just don't know what a "sentence" means in a python file.  I think what is meant is a python statement, but the docstrings should reflect that, or define what is meant by a sentence.
I agree here, the reason why I abused the term sentence for moving 
between statements is because there's no Emacs standard binding (nor 
concept) of moving between statements. Ideally 
python-nav-{backward,forward}-sentence must navigate blocks python code. 
Everything with an extra level of indentation after the block start must 
be considered part of the block (sentence). So given the following example:

     If something:
         do_this()
         do_that()

If the pointer is at the start of the if statement, and the user issues 
python-nav-forward-sentence he must be taken after the do_that() statement.

So what I'm going to do is to rename these existing functions to 
python-nav-{backward,forward}-statement and implement proper 
python-nav-{backward,forward}-sentence that would navigate blocks of code.

> That said, I did just notice that M-a (python-nav-backward-sentence) gets "stuck" on the comment in the test below.  If I put a blank line after the comment then it doesn't.
>
> print libgap('if 4>3 then\nprint("hi");\nfi')
> # Abort/segfault
> print libgap('SmallGroup(12,3)')
>
> I can create a new bug for that if desired.
>
> -Ivan
I noticed that too, there's no need to open a ticket for it, I'll work 
on that too while solving this ticket.


Thanks!

-- 
Fabián E. Gallina
Co-Founder of Anue
Skype: caffeineGalli
http://www.anue.biz/

bug#11899: 24.1.50; Weird names and unhelpful docstrings for some python function

[Chong Yidong]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

>>   python-nav-sentence-start
>>   python-nav-sentence-end
>>   python-nav-forward-sentence
>>   python-nav-backward-sentence
>> have weird names in the sense that they don't move by sentences.
>
> Indeed, thanks for catching that.  Fabián, can you take a look at it?

For consistency with the rest of the Emacs code base, I suggest dropping
the `nav', since other modes don't use that naming convention.  As for
the bug report, I don't have an opinion on whether it should be
`python-sentence-start' or `python-statement-start'.  If the former, it
would be nice if the docstring explains what "sentence" means in the
Python context.

bug#11899: 24.1.50; Weird names and unhelpful docstrings for some python function

[Stefan Monnier]

>     If something:
>         do_this()
>         do_that()

> If the pointer is at the start of the if statement, and the user issues
> python-nav-forward-sentence he must be taken after the do_that() statement.

That sounds like sexp-based navigation, then.

> python-nav-{backward,forward}-sentence that would navigate blocks of code.

I don't think "sentence" is a good word choice since there is no
accepted meaning of a "sentence" in the context of python code (or code
in general), AFAIK.

If you want to bind these commands to the same keys as
for/backward-sentence, that's fine, but better give them names related
to what they do, rather than to to this key-mapping choice.


        Stefan

bug#11899: 24.1.50; Weird names and unhelpful docstrings for some python function

[Leo]

On 2012-07-13 13:02 +0800, Chong Yidong wrote:
> For consistency with the rest of the Emacs code base, I suggest dropping
> the `nav', since other modes don't use that naming convention.  As for
> the bug report, I don't have an opinion on whether it should be
> `python-sentence-start' or `python-statement-start'.  If the former, it
> would be nice if the docstring explains what "sentence" means in the
> Python context.

In cc-mode:

M-a runs the command c-beginning-of-statement
M-e runs the command c-end-of-statement

Leo

bug#11899: 24.1.50; Weird names and unhelpful docstrings for some python function

[Fabián Ezequiel Gallina]

On 07/13/2012 09:20 AM, Stefan Monnier wrote:
>>      If something:
>>          do_this()
>>          do_that()
>> If the pointer is at the start of the if statement, and the user issues
>> python-nav-forward-sentence he must be taken after the do_that() statement.
> That sounds like sexp-based navigation, then.
>
>> python-nav-{backward,forward}-sentence that would navigate blocks of code.
> I don't think "sentence" is a good word choice since there is no
> accepted meaning of a "sentence" in the context of python code (or code
> in general), AFAIK.
>
> If you want to bind these commands to the same keys as
> for/backward-sentence, that's fine, but better give them names related
> to what they do, rather than to to this key-mapping choice.
>
>
>          Stefan
I just pushed some new navigation commands with proper documentation and 
names. Also there's a specialized forward-sexp-function included.

All of this is included in revno 109105.


Regards,

-- 
Fabián E. Gallina
Co-Founder of Anue
Skype: caffeineGalli
http://www.anue.biz/

bug#11899: 24.1.50; Weird names and unhelpful docstrings for some python function

[Ivan Andrus]

On Jul 16, 2012, at 3:22 PM, Fabián Ezequiel Gallina wrote:
> On 07/13/2012 09:20 AM, Stefan Monnier wrote:
>>>     If something:
>>>         do_this()
>>>         do_that()
>>> If the pointer is at the start of the if statement, and the user issues
>>> python-nav-forward-sentence he must be taken after the do_that() statement.
>> That sounds like sexp-based navigation, then.
>> 
>>> python-nav-{backward,forward}-sentence that would navigate blocks of code.
>> I don't think "sentence" is a good word choice since there is no
>> accepted meaning of a "sentence" in the context of python code (or code
>> in general), AFAIK.
>> 
>> If you want to bind these commands to the same keys as
>> for/backward-sentence, that's fine, but better give them names related
>> to what they do, rather than to to this key-mapping choice.
>> 
>> 
>>         Stefan
> I just pushed some new navigation commands with proper documentation and names. Also there's a specialized forward-sexp-function included.
> 
> All of this is included in revno 109105.

Excellent.  Thanks.

-Ivan

bug#11899: 24.1.50; Weird names and unhelpful docstrings for some python function

[Fabián Ezequiel Gallina]

On 07/17/2012 08:08 AM, Ivan Andrus wrote:
> Excellent. Thanks. -Ivan

I just double-checked things and did a couple of final renames.

Check revno 109127.


Regards,

-- 
Fabián E. Gallina
Co-Founder of Anue
http://www.anue.biz/