We Keep Coding

How a method call works in Python, and significance of bound methods [closed]

Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 1 year ago.
Improve this question
I have a basic question on how a method call really works in Python. I found this post and this one that are helpful, but not answering all my questions.
Basically, my understanding from Section 9.3.4 of Python documentation is that:
When an instance object calls its method, a search is done on the class object. If the matching function is found, the function object attached to the class object is called with the instance object as its first parameter.
My main questions are:
What is the significance of bound methods? Currently, a call to method is transferred to a call to function with the instance object as its first argument enabling the function to access the instance object. Why has Python adopted this approach, instead of each method directly processing its bound instance object? Any cons and pros for each of these approaches?
Can a bound method theoretically lead to a lower performance (slower execution), in case that a large number of instances call their own method simultaneously, which is seemingly equivalent to calling one single function object multiple times (in a serial fashion??) with different instances as the first argument per call?
I know I am missing some fundamentals here, and I would be grateful if anyone could please advise. Thank you for your time.

You skipped a step in what actually happens. Let's say you try to call foo.bar(baz), where foo is an instance of Foo.
First, an instance attribute named bar is looked for in the object foo. Most likely, it doesn't exist, as you typically don't want to shadow the actual method like this.
Next, bar is looked for as a class attribute in each class in the MRO of foo. For simplicity, assume you find it right away in Foo.
At this point, Foo.bar is a simple function object. But, because a function implements the descriptor protocol, you don't actually get the function object itself: you get the result of Foo.bar.__get__(foo, Foo). That result is the bound method: an instance of method which wraps both the original function and the object foo. (For a better description of what is going on, see the descriptor protocol how-to guide.
Calling an instance of method causes the underlying function to be called, with foo as the first argument and baz as an additional object. Whatever the function returns is what the method instance returns.
This is how foo.bar(baz) becomes Foo.bar(foo, baz), by way of Foo.bar.__get__(foo, Foo)(baz).
Although there is some additional overhead, it's not really significant compared to the benefit of having many different things simply be applications of the descriptor protocol. All of the following are implemented via descriptors, without having to add specific implementations of each to the language itself:
Instance methods
Class methods
Static methods
Properties
as well as the descriptor protocol being something you can implement in your own classes in order to provide specific behavior in a way that blends seamlessly with other Python conventions.

Best practice for the order of function arguments in Python [closed]

Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 2 years ago.
Improve this question
I often write functions that take one argument with data to be manipulated, and one or more additional arguments with specifications for the manipulation. If the "specification" parameters are optional, it makes sense to place them after the obligatory data argument:
sort(data, key=..., reverse=True)
But suppose both arguments (or several of them) are obligatory? The functions of the re module place the regexp (the manipulation) before the string (the data to be manipulated). Optional arguments still come last, of course.
re.search(r"[regexp]+", text, flags=re.I)
So here's the question: Putting optional arguments aside, are there any clear conventions (official PEP or established common practice) for how to order obligatory arguments based on their function/purpose? Back when I was first learning Python, I remember reading some claim to the effect that one of Python's advantages is that it has clear conventions, inter alia on this particular thing. But I am unable to retrieve any such information now.
In case it is not clear: I am kindly asking for pointers to established conventions or standards, not for advice on which order is "best."

This is one hell of a good question and I'm already excited to see other answers. I've never come across any conventions about functions arguments in Python except in PEP 8 where it states that:
Always use self for the first argument to instance methods.
Always use cls for the first argument to class methods.
If a function argument's name clashes with a reserved keyword, it is
generally better to append a single trailing underscore rather than
use an abbreviation or spelling corruption. Thus class_ is better than
clss. (Perhaps better is to avoid such clashes by using a synonym.)
In my opinion, functions parameter should always be in order of importance. I know importance is subjective but you generally can determine which of the parameters is the most important to your function. Since StackOverflow is not about opinion take this with a grain of salt.
So putting aside opinions, I think your question is relevant but sometimes questions leads to other discussions. If you have numerous parameters, your function is probably doing too much stuff. According to a lot of ressources, you should try to use only one parameter and avoid using more than three where the latter is considered as the worst case scenario. So, most of the time ordering parameters won't impact readability that much if you keep that in mind.

I try to order parameters to help code readability (literate programming).
ex:
system.add(user, user_database) # add a user to a database
system.add(user_database, user) # add a database to a user(?)
This usually coincide with #scharette's opinion, the "most important" parameter is the object for which the function was created for. But as (he) stated it's subjective, it could be argued the database is the most important object in a database system library.
Reading code should reveal intent on first read; reading a set of function definitions should reveal what they do.

What is a good way to order methods in a Python class? [closed]

Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed last year.
The community reviewed whether to reopen this question last year and left it closed:
Original close reason(s) were not resolved
Improve this question
I want to order methods in a Python class, but I don't know what the correct order is.
When I extract methods in Eclipse with PyDev, Eclipse puts the extracted method on top of the modified method. But this puts the lower level details before the higher level details. According to Uncle Bob, I should do the opposite, so that my code reads like the headlines of a newspaper. When I program in Java I just follow his advice.
What is the best practice for Python?

As others have pointed out, there is no right way to order your methods. Maybe a PEP suggestion would be useful, but anyway. Let me try to approach your question as objectively as possible.
Interfaces first: Public methods and Python magic functions define the interface of the class. Most of the time, you and other developers want to use a class rather than change it. Thus they will be interested in the interface of that class. Putting it first in the source code avoids scrolling through implementation details you don't care about.
Properties, magic methods, public methods: It's hard to define the best order between those three, which are all part of the interface of the class. As Ethan Furman says, it's most important to stick with one system for the whole project. Generally, people expect __init__() to the best first function in the class so I follow up with the other magic methods right below.
Reading order: Basically, there are two ways to tell a story: Bottom-up or top-down. By putting high-level functions first, a developer can get a rough understanding of the class by reading the first couple of lines. Otherwise, one would have to read the whole class in order to get any understanding of the class and most developers don't have the time for that. As a rule of thumb, put methods above all methods called from their body.
Class methods and static methods: Usually, this is implied by the reading order explained above. Normal methods can call all methods times and thus come first. Class methods can only call class methods and static methods and come next. Static methods cannot call other methods of the class and come last.
Most of these rules are not Python-specific by the way. I'm not aware of a language that enforces method order.

There is no one correct order. Pick a system and stick with it. The one I use is:
class SomeClass(object):
def __magic_methods__(self):
"magic methods first, usually in alphabetical order"
def _private_method(self):
"worker methods next, also in alphabetical order"
def a_method(self):
"then normal methods, also in alphabetical order"

I do something similar to Ethan that I saw in Django's source, where the main difference is big "############" block comments to delimit the areas.
For example,
class SomeClass(object):
#################
# Magic Methods #
#################
def __magic_methods__(self):
"magic methods first"
##################
# Public Methods #
##################
def a_method(self):
"then normal methods, in order of importance"
###################
# Private Methods #
###################
def _private_method(self):
"then worker methods, grouped by importance or related function"
Obviously this is less useful for smaller classes.

The code
class Bar(_Foo):
pass
class _Foo:
pass
raises an exception since the class _Foo has to be defined before it is used. You can find similar exception-raising example for functions too:
def bar(f=_foo):
pass
def _foo():
pass
Given these examples it makes sense to generally define private classes and functions before the public ones. That's why it makes sense to keep the consistency and to define also private methods before the public ones.

Function overloading in Python: Missing [closed]

It's difficult to tell what is being asked here. This question is ambiguous, vague, incomplete, overly broad, or rhetorical and cannot be reasonably answered in its current form. For help clarifying this question so that it can be reopened, visit the help center.
Closed 13 years ago.
As function overloading says:
Function overloading is absent in Python.
As far as I feel this a big handicap since its also an object-oriented (OO) language. Initially I found that unable to differentiate between the argument types was difficult, but the dynamic nature of Python made it easy (e.g. list, tuples, strings are much similar).
However, counting the number of arguments passed and then doing the job is like an overkill.

Now, unless you're trying to write C++ code using Python syntax, what would you need overloading for?
I think it's exactly opposite. Overloading is only necessary to make strongly-typed languages act more like Python. In Python you have keyword argument, and you have *args and **kwargs.
See for example: What is a clean, Pythonic way to have multiple constructors in Python?

As unwind noted, keyword arguments with default values can go a long way.
I'll also state that in my opinion, it goes against the spirit of Python to worry a lot about what types are passed into methods. In Python, I think it's more accepted to use duck typing -- asking what an object can do, rather than what it is.
Thus, if your method may accept a string or a tuple, you might do something like this:
def print_names(names):
"""Takes a space-delimited string or an iterable"""
try:
for name in names.split(): # string case
print name
except AttributeError:
for name in names:
print name
Then you could do either of these:
print_names("Ryan Billy")
print_names(("Ryan", "Billy"))
Although an API like that sometimes indicates a design problem.

You don't need function overloading, as you have the *args and **kwargs arguments.
The fact is that function overloading is based on the idea that passing different types you will execute different code. If you have a dynamically typed language like Python, you should not distinguish by type, but you should deal with interfaces and their compliance with the code you write.
For example, if you have code that can handle either an integer, or a list of integers, you can try iterating on it and if you are not able to, then you assume it's an integer and go forward. Of course it could be a float, but as far as the behavior is concerned, if a float and an int appear to be the same, then they can be interchanged.

Oftentimes you see the suggestion use use keyword arguments, with default values, instead. Look into that.

You can pass a mutable container datatype into a function, and it can contain anything you want.
If you need a different functionality, name the functions differently, or if you need the same interface, just write an interface function (or method) that calls the functions appropriately based on the data received.
It took a while to me to get adjusted to this coming from Java, but it really isn't a "big handicap".

How to write meaningful docstrings? [closed]

Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 21 days ago.
Improve this question
What, in Your opinion is a meaningful docstring? What do You expect to be described there?
For example, consider this Python class's __init__:
def __init__(self, name, value, displayName=None, matchingRule="strict"):
"""
name - field name
value - field value
displayName - nice display name, if empty will be set to field name
matchingRule - I have no idea what this does, set to strict by default
"""
Do you find this meaningful? Post Your good/bad examples for all to know (and a general answer so it can be accepted).

I agree with "Anything that you can't tell from the method's signature". It might also mean to explain what a method/function returns.
You might also want to use Sphinx (and reStructuredText syntax) for documentation purposes inside your docstrings. That way you can include this in your documentation easily. For an example check out e.g. repoze.bfg which uses this extensively (example file, documentation example).
Another thing one can put in docstrings is also doctests. This might make sense esp. for module or class docstrings as you can also show that way how to use it and have this testable at the same time.

From PEP 8:
Conventions for writing good documentation strings (a.k.a.
"docstrings") are immortalized in PEP 257.
Write docstrings for all public modules, functions, classes, and methods. Docstrings are not necessary for non-public methods, but you
should have a comment that describes what the method does. This
comment should appear after the "def" line.
PEP 257 describes good docstring conventions. Note that most importantly, the """ that ends a multiline docstring should be on a
line by itself, and preferably preceded by a blank line.
For one liner docstrings, it's okay to keep the closing """ on the same line.

Check out numpy's docstrings for good examples (e.g. http://github.com/numpy/numpy/blob/master/numpy/core/numeric.py).
The docstrings are split into several sections and look like this:
Compute the sum of the elements of a list.
Parameters
----------
foo: sequence of ints
The list of integers to sum up.
Returns
-------
res: int
sum of elements of foo
See also
--------
cumsum: compute cumulative sum of elemenents

What should go there:
Anything that you can't tell from the method's signature. In this case the only bit useful is: displayName - if empty will be set to field name.

The most striking things I can think of to include in a docstring are the things that aren't obvious. Usually this includes type information, or capability requirements - eg. "Requires a file-like object". In some cases this will be evident from the signature, not so in other cases.
Another useful thing you can put in to your docstrings is a doctest.

I like to use the documentation to describe in as much detail as possible what the function does, especially the behavior at corner cases (a.k.a. edge cases). Ideally, a programmer using the function should never have to look at the source code - in practice, that means that whenever another programmer does have to look at source code to figure out some detail of how the function works, that detail probably should have been mentioned in the documentation. As Freddy said, anything that doesn't add any detail to the method's signature probably shouldn't be in a documentation string.

Generally purpose of adding adding doc string in starting of function is to describe function, what it does, what it would return, and description about parameters. You can add implementation details if required. Even you can add details about author who wrote the code for future developer.