Python Style Guide

[alexweav]

Casing

Use PascalCase for classes. class MyClass(object):

Use PascalCase for methods. def MyMethod(args):

Python prefers snake_case for local and class variables. self.my_variable this_is_a_local_variable or self.myVariable thisIsALocalVariable

CAPS_WITH_UNDERSCORES for global constants PI

Classes

This is intended to be an object-oriented project. Functions should never be outside of a class, unless they are trivial or simplify an API.

i don't have an example for this one

Exceptions include a main function, as well as auxiliary/related things such as command-line argument parsing, etc. Should argument parsing be a class???

Never access class variables directly. Expose properties for variables that you want to be readable or modifiable. DO: var = object.GetVariable() DON'T: var = object.variable

If a class doesn't inherit from anything, inherit directly from object. Thoughts on this? DO:class MyClass(object): DON'T:class MyClass:

Abstract methods are known to suck in Python. Common practice seems to involve throwing a NotImplementedError for abstract methods with a helpful error message. Thoughts?

class MyAbstractClass(object):

    def MyAbstractMethod(args):
        raise NotImplementedError(`Calling an abstract method`)

Add an I to the beginning of the name of any interface class. DO:class IMyInterface(object): DON'T:class MyInterface(object):

Don't use C++ style multiple inheritance. Classes can inherit from an arbitrary number of interfaces, but only one abstract or concrete class. DO: class MyClass(BaseClass, IMyInterface): DON'T: class MyClass(BaseClass, OtherBaseClass):

Methods

Python supports typed annotations for method signatures. Do we want this? I personally hate dynamic typing with object oriented programming, so I would be for it. Not everyone likes it though since the syntax is a little unusual. WITHOUT:

def AddFive(num):
    return num + 5

WITH:

def AddFive(num: int) -> int:
    return num + 5

Comments

Add a comment above each class.

"""
Does something interesting.
"""
class MyClass(object):

Add a comment above each method. Do we want this? Keep in mind this includes stuff as simple as properties, which could seem unnecessary. Could reduce this to "Add a comment above each non-trivial method." NONTRIVIAL:

"""
Does something interesting.
"""
def MyMethod(args):

TRIVIAL:

"""
Gets the IP Address
"""
def GetIp():

Use triple quotes for comments describing classes, methods, etc. Use #-comments for simple line annotations.

"""
I describe MyClass
"""
class MyClass(object):

statement1
statement2   # Does something special
statement3

[mariots]

What about using the PEP8 style guide?

[alexweav]

Used the Google Python Style Guide for most of this, a lot of it is duplicated.

Some stuff here is different, not sure how far we should go with it.

[mariots]

I like the idea of method signatures, we should show the return value

[mariots]

I like the idea of putting comments above each method after reading through the packatizer #18 pr