Separate sections in Python [closed]

Question

I was wondering whether there is a best practice to separate chunks of code in Python. In MATLAB, for example, two comment signs (%%) create a code section. At the moment, I am doing:

####
## Import libraries
####

import _mssql #Binary here: http://www.lfd.uci.edu/~gohlke/pythonlibs/#pymssql

####
## Connect to db + Query the data
####

q_file = open ("query.txt", "r")
query = q_file.read().replace('\n', '')

##Connect to the database
conn = _mssql.connect(server='', user='',
                      password='', database='')

##Query the database
conn.execute_query(query)
for row in conn:
    print(row)

####
## Data filtering
####

[...]

Answer 1

Top level use modules, implement separate parts in their respective modules, then refer to those in your main:

import random
import time

if time.time() > random.random():
    pass

Next level (optional, use sparingly) use classes

class Foo:
    def function1():
        pass

class Bar:
    def function2():
        pass

Next level, what you need, use functions

def connect(...):
    filename = ...
    params = ...(filename)
    return mysql.connect(*params)

def mainloop(...):
    for xx in connect():
        pass

Sublevel use blocks

def foo(path=None, port=None):
    if not path:
        filename = ...
        path = ...(filename)

    if not port:
        foobar = ...
        port = ...(foobar)

    xxx.connect(path, port)

Subsublevel use blank lines and comments

def foo(...):
    bar.bar()

    assert path  # <-- this is essentially a comment
    smth_with(path)
    some_other()
    data = xxx.yyy()

    assert data
    foo = blahblah
    bar = lambda: blahblah
    filtered = filter(yada, data)

    # data is clean at this point  # <-- an actual comment
    for x, y in data:
        foo.bar.baz()

Final thoughts large comment blocks like in OQ show "code smell." You are right to start wondering how to organise your code at this point :)

Answer 2

Python quite naturally offers a modular structure, and documentation strings for every level of structure.

Your comments generally would belong as function names or method descriptions. Then the code reads naturally. (Some comments are so obvious as to be useless, like "Import libraries".)

"""
Perform stuff.  Obviously this documentation should be more specific in reality.
"""

import _mssql  # Binary here: http://www.lfd.uci.edu/~gohlke/pythonlibs/#pymssql


def run_query(filename):
    """
    Open connection to database, run the query in the file, and
    return rows as a list.
    """
    rows = []

    # Minor tweak: "with" takes care of closing the file when you're done
    with open (filename, "r") as q_file:
        query = q_file.read().replace('\n', '')

    conn = _mssql.connect(server='', user='',
                      password='', database='')

    conn.execute_query(query)
    for row in conn:
        # Maybe use yield here instead of reading all the results into memory
        rows.append(row)

    return rows

def filter_rows(rows):
    """
    Filter a list of rows: Remove any rows containing 'Albuquerque'.
    """
    # ....

results = filter_rows(run_query("query.txt"))

See further PEP 257 to guide your documentation efforts.