We Keep Coding

Keeping alias types simple in Python documentation?

I'm trying to use the typing module to document my Python package, and I have a number of situations where several different types are allowable for a function parameter. For instance, you can either pass a number, an Envelope object (one of the classes in my package), or a list of numbers from which an Envelope is constructed, or a list of lists of numbers from which an envelope is constructed. So I make an alias type as follows:
NumberOrEnvelope = Union[Sequence[Real], Sequence[Sequence[Real]], Real, Envelope]
Then I write the function:
def example_function(parameter: NumberOrEnvelope):
...
And that looks great to me. However, when I create the documentation using Sphinx, I end up with this horrifically unreadable function signature:
example_function(parameter: Union[Sequence[numbers.Real], Sequence[Sequence[numbers.Real]], numbers.Real, expenvelope.envelope.Envelope])
Same thing also with the hints that pop up when I start to try to use the function in PyCharm.
Is there some way I can have it just leave it as "NumberOrEnvelope". Ideally that would also link in the documentation to a clarification of what "NumberOrEnvelope" is, though even if it didn't it would be way better than what's appearing now.

I had the same issue and used https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_type_aliases, introduced in version 3.3.
In your sphinx conf.py, insert this section. It does not seem to make much sense at the first sight, but does the trick:
autodoc_type_aliases = dict(NumberOrEnvelope='NumberOrEnvelope')
Warning: It only works in modules that start with from __future__ import annotation
Note: If there is a target in the documentation, type references even have a hyperlink to the definition. I have classes, documented elsewhere with autoclass, which are used as types of function parameters, and the docs show the nice names of the types with links.

Support for this appears to be in the works.
See Issue #6518.
That issue can be closed by the recent updates to Pull Request #8007 (under review).
If you want the fix ASAP, you can perhaps try using that build.

EDIT: This doesn't quite work, sadly.
Turns out after a little more searching, I found what I was looking for. Instead of:
NumberOrEnvelope = Union[Sequence[Real], Sequence[Sequence[Real]], Real, Envelope]
I found that you can create your own compound type that does the same thing:
NumberOrEnvelope = TypeVar("NumberOrEnvelope", Sequence[Real], Sequence[Sequence[Real]], Real, Envelope)
This displays in documentation as "NumberOrEnvelope", just as I wanted.

In python, "request.args.get" returns what type of variable?

Please bear with me as I am a beginner in python. I'm using a framework to change values of my drone's parameters. One of the command I would like to use is vehicle.parameters['INJECT_TO_GPS']=100. When I use
vehicle.parameters['GPS_TO_INJECT']=100
It works well and changes it to 100. Now I want to include this in a function (I'm using flask to get the value of a from a web page), so If I use:
def change_value():
a = request.args.get('a', 0)
vehicle.parameters['INJECT_TO_GPS']=a
It does not work, printing me:
error: required argument is not a float
I also tried:
vehicle.parameters['INJECT_TO_GPS']=float(a)
But in this, it complains that it has to be a string...
What is wrong with it ? thanks a lot in advance

To know the type You can use inbuilt function type or isinstance to test that it belongs to that class:
print(type(a))
print(isinstance(a , class_or_type_you_want_check))

Ipdb and method documentation

I have to analyze methods a foreign API, and how I usually do it it to write a test script, or find an example code, do a
ipdb.set_trace()
Where I want to experiment, and than take a look at currently available variables, objects and their methods. However, when I want to check the documentation the way Ipython offers
object.method?
I get
*** SyntaxError: invalid syntax (<stdin>, line 1)
If I try
help(object.method)
It gives
*** No help on (object.method)
Does that mean that there is no documentation for the selected method, or am I using the wrong way of calling it?

Actually !help(object.method) works, you just need to signify with ! that it's a python command, not ipdb help command. Though convenient question mark doesn't work that way unfortunately.

The help() function is actually a wrapper around pydoc.help() which means that you can do something like:
ipdb> import math
ipdb> import pydoc
ipdb> pydoc.help(math.log)

Eclipse pydev auto-suggestions don't work in some cases

My question is probably stupid and I hope somebody has succeeded in solving this issue.
Sometimes I cannot see right suggestions in auto-completion box (Eclipse 3.5.2, PyDev 1.5.7). For example:
import email
fp = open('my.eml', 'rb')
msg = email.message_from_file(fp)
msg now is a Message object. And functions like get_payload() works fine.
msg.get_payload()
But I don't get get_payload() in auto-completion list.
I think PyDev has no idea of what msg is, so it doesn't know what to show.
Maybe I should import something else, not only email module?
Thanks in advance!

I struggled with this question quite a bit too, until I came across this link. I used the second solution suggested in that link, and it works like a charm.
Basically you need to insert assert isinstance(msg, Message) after you get msg from the function call.

Chances are, the current PyDev build hasn't gone to a point to be able to extract from a function (message_from_file() in your case) to know what kind of object it returns in order to provide auto-completion hinting.
See http://sourceforge.net/projects/pydev/forums/forum/293649/topic/3697707.
Edit: I believe there is interest in PyDev to support the new Python 3 function syntax, PEP 3107, which will solve some of your problems ... in the future.

I know #type in docstring works. As in:
from collections import deque
def foo(a):
''' code completion sample
#type a: deque
'''
return a.popleft() # Code completion will work here
I have not been able to find a way to do it inline within code (except in ways mentioned elsewhere where you simply pretend to assign the variable an instance of a type) as in:
from collections import deque
def foo(a):
''' code completion sample '''
if false: a = deque()
return a.popleft() # Code completion will also work here
But I'm not fond of this method because it probably imposes some performance / code size penalty. I don't know / haven't checked if Python is smart enough to remove this assignment during compile time.
Thanks to SiSoie, here's a link to page explaining possibilities.

Ruby equivalent to Python's help()?

When working in interactive Python, I tend to rely on the built-in help() function to tell me what something expects and/or returns, and print out any documentation that might help me. Is there a Ruby equivalent to this function?
I'm looking for something I could use in irb. For example, in interactive Python I could type:
>>> help(1)
which would then print
Help on int object:
class int(object) | int(x[, base])
-> integer | |
Convert a string or number to an integer, if possible. A ...

It's now late 2014 and here's the two ways to get the Python help() *similarity, as long as you have the Ruby Docs installed:
From inside irb, You can call the help method with a string describing what you're looking for.
Example 1: help 'Array' for the Array class
Example 2: help 'Array#each' for the Array class each method.
From the command line, outside of irb, you can use the ri program:
Example 1: ri 'Array' for the Array class
Example 2: ri 'Array#each' for the Array class each method.
* Not quite as good as Python's, but still better than nothing

It's definitely a poor cousin to iPython's help, and one of the main features I miss after moving to Ruby, but you can also use ri from within irb. I'd recommend the wirble gem as an easy way to set this up.

Try using ri from the command line.
It takes a class name, method, or module as an argument, and gives you appropriate documentation. Many popular gems come with this form of documentation, as well, so it should typically work even beyond the scope of core Ruby modules.

There's supposed to be irb_help. But like mentioned in that post, it's broken in my ruby install as well.

For quick shell access to ruby documentation, just type ri followed by the method you're wanting to learn more about (from your shell).
For example:
ri puts
This must be fired up in your shell, not your irb (interactive ruby environment)
If you're in your irb environment, then another way, is to simply type help followed by the method you want to learn more about as follows:
help puts
However, this assumes that you have configured your Ruby environment correctly for that (help) to work properly within irb. I usually just have another shell open, and just use the ri directly for quick access when I'm in doubt about a certain method or arguments to a method.