Update docstrings to match PEP257
This commit is contained in:
1 parent
7ff9aecd4e
commit
b8a40457ee
40 files changed
+371
-483
No files matched your search
@@ -1,6 +1,4 @@
|
||||
"""
|
||||
homeassistant.components.recorder
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Component that records all events and state changes. Allows other components
|
||||
to query this database.
|
||||
|
||||
@@ -35,14 +33,14 @@ _LOGGER = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def query(sql_query, arguments=None):
|
||||
""" Query the database. """
|
||||
"""Query the database."""
|
||||
_verify_instance()
|
||||
|
||||
return _INSTANCE.query(sql_query, arguments)
|
||||
|
||||
|
||||
def query_states(state_query, arguments=None):
|
||||
""" Query the database and return a list of states. """
|
||||
"""Query the database and return a list of states."""
|
||||
return [
|
||||
row for row in
|
||||
(row_to_state(row) for row in query(state_query, arguments))
|
||||
@@ -50,7 +48,7 @@ def query_states(state_query, arguments=None):
|
||||
|
||||
|
||||
def query_events(event_query, arguments=None):
|
||||
""" Query the database and return a list of states. """
|
||||
"""Query the database and return a list of states."""
|
||||
return [
|
||||
row for row in
|
||||
(row_to_event(row) for row in query(event_query, arguments))
|
||||
@@ -58,7 +56,7 @@ def query_events(event_query, arguments=None):
|
||||
|
||||
|
||||
def row_to_state(row):
|
||||
""" Convert a database row to a state. """
|
||||
"""Convert a database row to a state."""
|
||||
try:
|
||||
return State(
|
||||
row[1], row[2], json.loads(row[3]),
|
||||
@@ -71,7 +69,7 @@ def row_to_state(row):
|
||||
|
||||
|
||||
def row_to_event(row):
|
||||
""" Convert a databse row to an event. """
|
||||
"""Convert a databse row to an event."""
|
||||
try:
|
||||
return Event(row[1], json.loads(row[2]), EventOrigin(row[3]),
|
||||
dt_util.utc_from_timestamp(row[5]))
|
||||
@@ -98,7 +96,7 @@ def run_information(point_in_time=None):
|
||||
|
||||
|
||||
def setup(hass, config):
|
||||
""" Setup the recorder. """
|
||||
"""Setup the recorder."""
|
||||
# pylint: disable=global-statement
|
||||
global _INSTANCE
|
||||
|
||||
@@ -108,7 +106,7 @@ def setup(hass, config):
|
||||
|
||||
|
||||
class RecorderRun(object):
|
||||
""" Represents a recorder run. """
|
||||
"""Represents a recorder run."""
|
||||
def __init__(self, row=None):
|
||||
self.end = None
|
||||
|
||||
@@ -160,7 +158,7 @@ class RecorderRun(object):
|
||||
|
||||
|
||||
class Recorder(threading.Thread):
|
||||
""" Threaded recorder class """
|
||||
"""A threaded recorder class."""
|
||||
def __init__(self, hass):
|
||||
threading.Thread.__init__(self)
|
||||
|
||||
@@ -173,7 +171,7 @@ class Recorder(threading.Thread):
|
||||
self.utc_offset = dt_util.now().utcoffset().total_seconds()
|
||||
|
||||
def start_recording(event):
|
||||
""" Start recording. """
|
||||
"""Start recording."""
|
||||
self.start()
|
||||
|
||||
hass.bus.listen_once(EVENT_HOMEASSISTANT_START, start_recording)
|
||||
@@ -181,7 +179,7 @@ class Recorder(threading.Thread):
|
||||
hass.bus.listen(MATCH_ALL, self.event_listener)
|
||||
|
||||
def run(self):
|
||||
""" Start processing events to save. """
|
||||
"""Start processing events to save."""
|
||||
self._setup_connection()
|
||||
self._setup_run()
|
||||
|
||||
@@ -215,12 +213,12 @@ class Recorder(threading.Thread):
|
||||
self.queue.put(event)
|
||||
|
||||
def shutdown(self, event):
|
||||
""" Tells the recorder to shut down. """
|
||||
"""Tells the recorder to shut down."""
|
||||
self.queue.put(self.quit_object)
|
||||
self.block_till_done()
|
||||
|
||||
def record_state(self, entity_id, state, event_id):
|
||||
""" Save a state to the database. """
|
||||
"""Save a state to the database."""
|
||||
now = dt_util.utcnow()
|
||||
|
||||
# State got deleted
|
||||
@@ -251,7 +249,7 @@ class Recorder(threading.Thread):
|
||||
info)
|
||||
|
||||
def record_event(self, event):
|
||||
""" Save an event to the database. """
|
||||
"""Save an event to the database."""
|
||||
info = (
|
||||
event.event_type, json.dumps(event.data, cls=JSONEncoder),
|
||||
str(event.origin), dt_util.utcnow(), event.time_fired,
|
||||
@@ -292,11 +290,11 @@ class Recorder(threading.Thread):
|
||||
return []
|
||||
|
||||
def block_till_done(self):
|
||||
""" Blocks till all events processed. """
|
||||
"""Blocks till all events processed."""
|
||||
self.queue.join()
|
||||
|
||||
def _setup_connection(self):
|
||||
""" Ensure database is ready to fly. """
|
||||
"""Ensure database is ready to fly."""
|
||||
db_path = self.hass.config.path(DB_FILE)
|
||||
self.conn = sqlite3.connect(db_path, check_same_thread=False)
|
||||
self.conn.row_factory = sqlite3.Row
|
||||
@@ -305,15 +303,15 @@ class Recorder(threading.Thread):
|
||||
# without the STOP event being fired.
|
||||
atexit.register(self._close_connection)
|
||||
|
||||
# Have datetime objects be saved as integers
|
||||
# Have datetime objects be saved as integers.
|
||||
sqlite3.register_adapter(date, _adapt_datetime)
|
||||
sqlite3.register_adapter(datetime, _adapt_datetime)
|
||||
|
||||
# Validate we are on the correct schema or that we have to migrate
|
||||
# Validate we are on the correct schema or that we have to migrate.
|
||||
cur = self.conn.cursor()
|
||||
|
||||
def save_migration(migration_id):
|
||||
""" Save and commit a migration to the database. """
|
||||
"""Save and commit a migration to the database."""
|
||||
cur.execute('INSERT INTO schema_version VALUES (?, ?)',
|
||||
(migration_id, dt_util.utcnow()))
|
||||
self.conn.commit()
|
||||
@@ -324,7 +322,7 @@ class Recorder(threading.Thread):
|
||||
migration_id = cur.fetchone()[0] or 0
|
||||
|
||||
except sqlite3.OperationalError:
|
||||
# The table does not exist
|
||||
# The table does not exist.
|
||||
cur.execute('CREATE TABLE schema_version ('
|
||||
'migration_id integer primary key, performed integer)')
|
||||
migration_id = 0
|
||||
@@ -399,7 +397,7 @@ class Recorder(threading.Thread):
|
||||
save_migration(3)
|
||||
|
||||
if migration_id < 4:
|
||||
# We had a bug where we did not save utc offset for recorder runs
|
||||
# We had a bug where we did not save utc offset for recorder runs.
|
||||
cur.execute(
|
||||
"""UPDATE recorder_runs SET utc_offset=?
|
||||
WHERE utc_offset IS NULL""", [self.utc_offset])
|
||||
@@ -412,15 +410,15 @@ class Recorder(threading.Thread):
|
||||
save_migration(4)
|
||||
|
||||
if migration_id < 5:
|
||||
# Add domain so that thermostat graphs look right
|
||||
# Add domain so that thermostat graphs look right.
|
||||
try:
|
||||
cur.execute("""
|
||||
ALTER TABLE states
|
||||
ADD COLUMN domain text
|
||||
""")
|
||||
except sqlite3.OperationalError:
|
||||
# We had a bug in this migration for a while on dev
|
||||
# Without this, dev-users will have to throw away their db
|
||||
# We had a bug in this migration for a while on dev.
|
||||
# Without this, dev-users will have to throw away their db.
|
||||
pass
|
||||
|
||||
# TravisCI has Python compiled against an old version of SQLite3
|
||||
@@ -429,13 +427,13 @@ class Recorder(threading.Thread):
|
||||
"instr", 2,
|
||||
lambda string, substring: string.find(substring) + 1)
|
||||
|
||||
# populate domain with defaults
|
||||
# Populate domain with defaults.
|
||||
cur.execute("""
|
||||
UPDATE states
|
||||
set domain=substr(entity_id, 0, instr(entity_id, '.'))
|
||||
""")
|
||||
|
||||
# add indexes we are going to use a lot on selects
|
||||
# Add indexes we are going to use a lot on selects.
|
||||
cur.execute("""
|
||||
CREATE INDEX states__state_changes ON
|
||||
states (last_changed, last_updated, entity_id)""")
|
||||
@@ -445,13 +443,13 @@ class Recorder(threading.Thread):
|
||||
save_migration(5)
|
||||
|
||||
def _close_connection(self):
|
||||
""" Close connection to the database. """
|
||||
"""Close connection to the database."""
|
||||
_LOGGER.info("Closing database")
|
||||
atexit.unregister(self._close_connection)
|
||||
self.conn.close()
|
||||
|
||||
def _setup_run(self):
|
||||
""" Log the start of the current run. """
|
||||
"""Log the start of the current run."""
|
||||
if self.query("""UPDATE recorder_runs SET end=?, closed_incorrect=1
|
||||
WHERE end IS NULL""", (self.recording_start, ),
|
||||
return_value=RETURN_ROWCOUNT):
|
||||
@@ -464,18 +462,18 @@ class Recorder(threading.Thread):
|
||||
(self.recording_start, dt_util.utcnow(), self.utc_offset))
|
||||
|
||||
def _close_run(self):
|
||||
""" Save end time for current run. """
|
||||
"""Save end time for current run."""
|
||||
self.query(
|
||||
"UPDATE recorder_runs SET end=? WHERE start=?",
|
||||
(dt_util.utcnow(), self.recording_start))
|
||||
|
||||
|
||||
def _adapt_datetime(datetimestamp):
|
||||
""" Turn a datetime into an integer for in the DB. """
|
||||
"""Turn a datetime into an integer for in the DB."""
|
||||
return dt_util.as_utc(datetimestamp.replace(microsecond=0)).timestamp()
|
||||
|
||||
|
||||
def _verify_instance():
|
||||
""" Throws error if recorder not initialized. """
|
||||
"""Throws error if recorder not initialized."""
|
||||
if _INSTANCE is None:
|
||||
raise RuntimeError("Recorder not initialized.")
|
||||
Reference in new issue
Block a user