Add example code for SQLAlchemy

Author: gjbex

source-code/db-access/ExperimentDB/.gitignore

@@ -0,0 +1 @@
+test.db

source-code/db-access/ExperimentDB/README.md

@@ -0,0 +1,16 @@
+# Orm
+Sample object-relational mapping (ORM) code implemented in Pythno's
+`sqlalchemy`.  Note that the database schema is not the same as that of
+the SQL examples in the parent directory.
+
+TODO: make schemas on slides, in SQL examples and ORM code consistent
+
+## What is it?
+1. `experiments.py`: class definitions for experiments, researchers and
+    samples, taking into account their associations.
+1. `create.py`: create database schema.
+1. `fill.py`: add some data to the database, illustrating back references.
+1. `view.py`: illustrate using back references when using objects.
+1. `orm_utils.py`: some helper functions for more convenient ORM usage.
+1. `shell.py`: a shell to work with the database using a domain specific
+    language.

source-code/db-access/ExperimentDB/create.py

@@ -0,0 +1,11 @@
+#!/usr/bin/env python
+
+from argparse import ArgumentParser
+from sqlalchemy import create_engine
+import experiments
+
+arg_parser = ArgumentParser(description='create tables in database')
+arg_parser.add_argument('db_name', help='name of DB to create')
+options = arg_parser.parse_args()
+engine = create_engine('sqlite:///{0}'.format(options.db_name))
+experiments.Base.metadata.create_all(engine)

source-code/db-access/ExperimentDB/experiments.py

@@ -0,0 +1,96 @@
+'''Module that defines classes to describe experiments, reseachers and
+   samples.  Experiments can have multple researchers associated to them,
+   and vice versa.  Samples are assigned to experiments, but a sample can
+   be used in a single experiment only.  Object Relational Mapping is
+   provided via SQLAlchemy.'''
+
+from sqlalchemy import (Column, ForeignKey, UniqueConstraint,
+                        Integer, String, DateTime, Table)
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import relationship, backref
+
+# Base class for all classes associated with tables in the database
+Base = declarative_base()
+
+# Table to hold the experiments-researchers many-to-many association
+staff_assignments = Table(
+    'staff_assignments', Base.metadata, Column(
+        'experiment_id',
+        Integer,
+        ForeignKey('experiments.experiment_id')
+    ),
+    Column(
+        'researcher_id',
+        Integer,
+        ForeignKey('researchers.researcher_id')
+    ),
+    UniqueConstraint('experiment_id', 'researcher_id')
+)
+
+
+class Experiment(Base):
+    '''An experiment have a description, a start date, and when finished,
+       an end date'''
+    __tablename__ = 'experiments'
+    experiment_id = Column(Integer, primary_key=True)
+    start_date = Column(DateTime, nullable=False)
+    end_date = Column(DateTime)
+    description = Column(String(2048), nullable=False)
+    researchers = relationship('Researcher', secondary=staff_assignments,
+                               backref='experiments')
+
+    def __str__(self):
+        '''string representation of an experiment'''
+        fmt_str = 'id {id:d}: {desc:s},\n\tstarted on {start}'
+        str_repr = fmt_str.format(id=self.experiment_id,
+                                  desc=self.description,
+                                  start=self.start_date)
+        if self.end_date:
+            str_repr = '{base:s}, ended on {end}'.format(base=str_repr,
+                                                         end=self.end_date)
+        return str_repr
+
+
+class Researcher(Base):
+    '''A researcher has a first name, a last name, and optionally, a
+       u-number, and description'''
+    __tablename__ = 'researchers'
+    researcher_id = Column(Integer, primary_key=True)
+    u_number = Column(String(20))
+    first_name = Column(String(20), nullable=False)
+    last_name = Column(String(20), nullable=False)
+    description = Column(String(20))
+
+    def __str__(self):
+        '''string representation of a researcher'''
+        fmt_str = 'id {id:d}: {last:s}, {first:s}'
+        str_repr = fmt_str.format(id=self.researcher_id,
+                                  last=self.last_name,
+                                  first=self.first_name)
+        if self.u_number:
+            str_repr = '{base} ({u_nr})'.format(base=str_repr,
+                                                u_nr=self.u_number)
+        if self.description:
+            str_repr = '{base}: {descr}'.format(base=str_repr,
+                                                descr=self.description)
+
+        return str_repr
+
+
+class Sample(Base):
+    '''A sample is associated to an experiment through the latter's ID,
+       and it has a description'''
+    __tablename__ = 'samples'
+    sample_id = Column(Integer, primary_key=True)
+    experiment_id = Column(Integer, ForeignKey('experiments.experiment_id'))
+    description = Column(String, nullable=False)
+    experiment = relationship('Experiment', backref=backref('samples'))
+
+    def __str__(self):
+        '''string representation of a sample'''
+        fmt_str = 'id {id:d}: {descr}'
+        str_repr = fmt_str.format(id=self.sample_id, descr=self.description)
+        if self.experiment_id:
+            str_repr = '{base} used in {e_id:d}'.format(base=str_repr,
+                                                        e_id=self.experiment_id)
+        return str_repr

source-code/db-access/ExperimentDB/fill.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python
+
+from argparse import ArgumentParser
+from datetime import datetime
+from experiments import Experiment, Researcher, Sample
+from orm_utils import create_session
+
+arg_parser = ArgumentParser(description='insert values into the database')
+arg_parser.add_argument('db_name', help='name of DB to create')
+options = arg_parser.parse_args()
+db_session = create_session(options.db_name)
+
+# create and add researchers
+nele = Researcher(first_name='Nele', last_name='Famaey')
+db_session.add(nele)
+heleen = Researcher(first_name='Heleen', last_name='Fehervary')
+db_session.add(heleen)
+db_session.commit()
+
+# create experiments
+exp1 = Experiment(
+    start_date=datetime(2015, 10, 23, 9, 11),
+    end_date=datetime(2015, 10, 25, 13, 43),
+    description='first experiment'
+)
+exp1.researchers.append(nele)
+exp1.samples.append(Sample(description='sample 1'))
+exp1.samples.append(Sample(description='sample 2'))
+db_session.add(exp1)
+exp2 = Experiment(
+    start_date=datetime(2015, 10, 27, 9, 5),
+    end_date=datetime(2015, 10, 28, 14, 53),
+    description='second experiment'
+)
+exp2.researchers.append(nele)
+exp2.researchers.append(heleen)
+exp2.samples.append(Sample(description='sample 3'))
+db_session.add(exp2)
+db_session.commit()

source-code/db-access/ExperimentDB/orm_utils.py

@@ -0,0 +1,13 @@
+'''Module with some convenient function for ORM usage'''
+
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+from experiments import Base
+
+
+def create_session(db_name):
+    '''Create a SQLAlchemy database session based on the provided name'''
+    engine = create_engine('sqlite:///{0}'.format(db_name))
+    Base.metadata.bind = engine
+    DBSession = sessionmaker(bind=engine)
+    return DBSession()

source-code/db-access/ExperimentDB/query.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python
+
+from datetime import datetime
+
+
+def convert2date(date_str):
+    '''convert a string representation 'yyyy-mm-dd' to a Python
+       datetime object'''
+    year, month, day = list(map(int, date_str.split('-')))
+    return datetime(year, month, day)
+
+if __name__ == '__main__':
+    from argparse import ArgumentParser
+    from experiments import Experiment, Researcher
+    from orm_utils import create_session
+    arg_parser = ArgumentParser(description='query the database')
+    arg_parser.add_argument('db_name', help='name of DB to create')
+    arg_parser.add_argument('--first_name',
+                            help='search for researcher by first name')
+    arg_parser.add_argument('--started_after',
+                            help='search experiments with a start date '
+                                 'later than the given one')
+    options = arg_parser.parse_args()
+    db_session = create_session(options.db_name)
+
+    if options.first_name:
+        researchers = db_session.query(Researcher).\
+                                 filter_by(first_name=options.first_name).\
+                                 all()
+        for researcher in researchers:
+            print(researcher)
+    elif options.started_after:
+        date_after = convert2date(options.started_after)
+        experiments = db_session.query(Experiment).\
+                         filter(Experiment.start_date > date_after).\
+                         all()
+        for experiment in experiments:
+            print(experiment)