From 8b8df99dce1aa78b107d2e05839475487f11a7f3 Mon Sep 17 00:00:00 2001 From: Davide Alberani Date: Sun, 22 Mar 2015 00:07:05 +0100 Subject: [PATCH 01/10] store new ID into scope --- angular_app/js/controllers.js | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/angular_app/js/controllers.js b/angular_app/js/controllers.js index 204e481..23cf34a 100644 --- a/angular_app/js/controllers.js +++ b/angular_app/js/controllers.js @@ -28,9 +28,9 @@ eventManControllers.controller('EventDetailsCtrl', ['$scope', 'Event', '$routePa } $scope.save = function() { if ($scope.event.id === undefined) { - Event.save($scope.event); + $scope.event = Event.save($scope.event); } else { - Event.update($scope.event); + $scope.event = Event.update($scope.event); } }; }] @@ -52,9 +52,9 @@ eventManControllers.controller('PersonDetailsCtrl', ['$scope', 'Person', '$route } $scope.save = function() { if ($scope.person.id === undefined) { - Person.save($scope.person); + $scope.person = Person.save($scope.person); } else { - Person.update($scope.person); + $scope.person = Person.update($scope.person); } }; }] From 0c65f0c87b16c64a2f059763189377d7c2a79d92 Mon Sep 17 00:00:00 2001 From: Davide Alberani Date: Sun, 22 Mar 2015 08:57:57 +0100 Subject: [PATCH 02/10] use strict mode --- angular_app/js/app.js | 2 ++ angular_app/js/services.js | 2 ++ 2 files changed, 4 insertions(+) diff --git a/angular_app/js/app.js b/angular_app/js/app.js index 3efc5cc..41063aa 100644 --- a/angular_app/js/app.js +++ b/angular_app/js/app.js @@ -1,3 +1,5 @@ +'use strict'; + var eventManApp = angular.module('eventManApp', [ 'ngRoute', 'eventManServices', diff --git a/angular_app/js/services.js b/angular_app/js/services.js index 6d0b352..334fc69 100644 --- a/angular_app/js/services.js +++ b/angular_app/js/services.js @@ -1,3 +1,5 @@ +'use strict'; + var eventManServices = angular.module('eventManServices', ['ngResource']); eventManServices.factory('Event', ['$resource', From 910515b2e70b77e7ea87ccfa7a35a56188c157fd Mon Sep 17 00:00:00 2001 From: Davide Alberani Date: Sun, 22 Mar 2015 08:58:25 +0100 Subject: [PATCH 03/10] docstring in Python code --- backend.py | 77 ++++++++++++++++++++++++++++++++++++++++++++-- eventman_server.py | 61 ++++++++++++++++++++++++++---------- 2 files changed, 119 insertions(+), 19 deletions(-) diff --git a/backend.py b/backend.py index 54457a8..e6dcf2e 100644 --- a/backend.py +++ b/backend.py @@ -1,6 +1,6 @@ -"""Event Man(ager) backend +"""Event Man(ager) database backend -Classes and functions used to manage events and attendants. +Classes and functions used to manage events and attendants database. """ import pymongo @@ -8,15 +8,29 @@ from bson.objectid import ObjectId class EventManDB(object): + """MongoDB connector.""" db = None connection = None def __init__(self, url=None, dbName='eventman'): + """Initialize the instance, connecting to the database. + + :param url: URL of the database + :type url: str (or None to connect to localhost) + """ self._url = url self._dbName = dbName self.connect(url) def connect(self, url=None, dbName=None): + """Connect to the database. + + :param url: URL of the database + :type url: str (or None to connect to localhost) + + :return: the database we're connected to + :rtype: :class:`~pymongo.database.Database` + """ if self.db is not None: return self.db if url: @@ -28,12 +42,32 @@ class EventManDB(object): return self.db def get(self, collection, _id): + """Get a single document with the specified `_id`. + + :param collection: search the document in this collection + :type collection: str + :param _id: unique ID of the document + :type _id: str or :class:`~bson.objectid.ObjectId` + + :return: the document with the given `_id` + :rtype: dict + """ if not isinstance(_id, ObjectId): _id = ObjectId(_id) results = self.query(collection, {'_id': _id}) return results and results[0] or {} def query(self, collection, query=None): + """Get multiple documents matching a query. + + :param collection: search for documents in this collection + :type collection: str + :param query: search for documents with those attributes + :type query: dict or None + + :return: list of matching documents + :rtype: list + """ db = self.connect() query = query or {} if'_id' in query and not isinstance(query['_id'], ObjectId): @@ -44,11 +78,33 @@ class EventManDB(object): return results def add(self, collection, data): + """Insert a new document. + + :param collection: insert the document in this collection + :type collection: str + :param data: the document to store + :type data: dict + + :return: the document, as created in the database + :rtype: dict + """ db = self.connect() _id = db[collection].insert(data) return self.get(collection, _id) def update(self, collection, _id, data): + """Update an existing document. + + :param collection: update a document in this collection + :type collection: str + :param _id: unique ID of the document to be updatd + :type _id: str or :class:`~bson.objectid.ObjectId` + :param data: the updated information to store + :type data: dict + + :return: the document, after the update + :rtype: dict + """ db = self.connect() data = data or {} if '_id' in data: @@ -56,3 +112,20 @@ class EventManDB(object): db[collection].update({'_id': ObjectId(_id)}, {'$set': data}) return self.get(collection, _id) + def delete(self, collection, _id_or_query=None, force=False): + """Remove one or more documents from a collection. + + :param collection: search the documents in this collection + :type collection: str + :param _id_or_query: unique ID of the document or query to match multiple documents + :type _id_or_query: str or :class:`~bson.objectid.ObjectId` or dict + :param force: force the deletion of all documents, when `_id_or_query` is empty + :type force: bool + """ + if not _id_or_query and not force: + return + db = self.connect() + if not isinstance(_id_or_query, (ObjectId, dict)): + _id_or_query = ObjectId(_id_or_query) + db[collection].remove(_id_or_query) + diff --git a/eventman_server.py b/eventman_server.py index 6e656b0..8fd05ea 100755 --- a/eventman_server.py +++ b/eventman_server.py @@ -18,58 +18,84 @@ from tornado import gen, escape import backend -class BaseHandler(tornado.web.RequestHandler): - def initialize(self, **kwargs): - for key, value in kwargs.iteritems(): - setattr(self, key, value) - - -class RootHandler(BaseHandler): - angular_app_path = os.path.join(os.path.dirname(__file__), "angular_app") - @gen.coroutine - def get(self): - with open(self.angular_app_path + "/index.html", 'r') as fd: - self.write(fd.read()) - - class ImprovedEncoder(json.JSONEncoder): + """Enhance the default JSON encoder to serialize datetime objects.""" def default(self, o): - if isinstance(o, datetime.datetime): + if isinstance(o, (datetime.datetime, datetime.date, + datetime.time, datetime.timedelta)): return str(o) return json.JSONEncoder.default(self, o) json._default_encoder = ImprovedEncoder() +class BaseHandler(tornado.web.RequestHandler): + """Base class for request handlers.""" + def initialize(self, **kwargs): + """Add every passed (key, value) as attributes of the instance.""" + for key, value in kwargs.iteritems(): + setattr(self, key, value) + + +class RootHandler(BaseHandler): + """Handler for the / path.""" + angular_app_path = os.path.join(os.path.dirname(__file__), "angular_app") + + @gen.coroutine + def get(self): + # serve the ./angular_app/index.html file + with open(self.angular_app_path + "/index.html", 'r') as fd: + self.write(fd.read()) + + class CollectionHandler(BaseHandler): + """Base class for handlers that need to interact with the database backend. + + Introduce basic CRUD operations.""" + # set of documents we're managing (a collection in MongoDB or a table in a SQL database) collection = None @gen.coroutine def get(self, id_=None): if id_ is not None: + # read a single document self.write(self.db.get(self.collection, id_)) else: + # return an object containing the list of all objects in the collection; + # e.g.: {'events': [{'_id': 'obj1-id, ...}, {'_id': 'obj2-id, ...}, ...]} + # Please, never return JSON lists that are not encapsulated in an object, + # to avoid XSS vulnerabilities. self.write({self.collection: self.db.query(self.collection)}) @gen.coroutine def post(self, id_=None, **kwargs): data = escape.json_decode(self.request.body or {}) if id_ is None: + # insert a new document newData = self.db.add(self.collection, data) else: + # update an existing document newData = self.db.update(self.collection, id_, data) self.write(newData) + # PUT is handled by the POST method put = post + class PersonsHandler(CollectionHandler): + """Handle requests for Persons.""" collection = 'persons' + class EventsHandler(CollectionHandler): + """Handle requests for Events.""" collection = 'events' -def main(): +def run(): + """Run the Tornado web application.""" + # command line arguments; can also be written in a configuration file, + # specified with the --config argument. define("port", default=5242, help="run on the given port", type=int) define("data", default=os.path.join(os.path.dirname(__file__), "data"), help="specify the directory used to store the data") @@ -82,6 +108,7 @@ def main(): callback=lambda path: tornado.options.parse_config_file(path, final=False)) tornado.options.parse_command_line() + # database backend connector db_connector = backend.EventManDB(url=options.mongodbURL, dbName=options.dbName) init_params = dict(db=db_connector) @@ -100,5 +127,5 @@ def main(): if __name__ == '__main__': - main() + run() From 488348df39961a3681d243172a0cc99830a10002 Mon Sep 17 00:00:00 2001 From: Davide Alberani Date: Sun, 22 Mar 2015 09:08:38 +0100 Subject: [PATCH 04/10] document the html --- angular_app/event-detail.html | 1 + angular_app/events-list.html | 41 ++++++++++++++++------------------ angular_app/index.html | 4 +++- angular_app/person-detail.html | 1 + angular_app/persons-list.html | 41 ++++++++++++++++------------------ 5 files changed, 43 insertions(+), 45 deletions(-) diff --git a/angular_app/event-detail.html b/angular_app/event-detail.html index 0f4c913..20b3f34 100644 --- a/angular_app/event-detail.html +++ b/angular_app/event-detail.html @@ -1,3 +1,4 @@ +
diff --git a/angular_app/events-list.html b/angular_app/events-list.html index d88a0ce..968da4c 100644 --- a/angular_app/events-list.html +++ b/angular_app/events-list.html @@ -1,28 +1,25 @@ -
+ +
-
- - Search: - Sort by: - - -
+
+ Search: + Sort by: + +
-
- - - -
+
+ +
-
+
diff --git a/angular_app/index.html b/angular_app/index.html index 3c9f06e..3abe275 100644 --- a/angular_app/index.html +++ b/angular_app/index.html @@ -1,6 +1,7 @@ + Event Man(ager) @@ -10,7 +11,6 @@ - Event Man(ager) @@ -24,6 +24,8 @@
+
diff --git a/angular_app/person-detail.html b/angular_app/person-detail.html index 8655799..c3f422f 100644 --- a/angular_app/person-detail.html +++ b/angular_app/person-detail.html @@ -1,3 +1,4 @@ +
diff --git a/angular_app/persons-list.html b/angular_app/persons-list.html index 9c94672..c040653 100644 --- a/angular_app/persons-list.html +++ b/angular_app/persons-list.html @@ -1,28 +1,25 @@ -
+ +
-
- - Search: - Sort by: - - -
+
+ Search: + Sort by: + +
-
- - - -
+
+ +
-
+
From 64cf4a580f8a3c7a352b957280db16108d28beec Mon Sep 17 00:00:00 2001 From: Davide Alberani Date: Sun, 22 Mar 2015 09:19:30 +0100 Subject: [PATCH 05/10] document JavaScript --- angular_app/js/app.js | 6 +++++- angular_app/js/controllers.js | 4 ++++ angular_app/js/services.js | 2 ++ 3 files changed, 11 insertions(+), 1 deletion(-) diff --git a/angular_app/js/app.js b/angular_app/js/app.js index 41063aa..eaeb50d 100644 --- a/angular_app/js/app.js +++ b/angular_app/js/app.js @@ -1,5 +1,6 @@ 'use strict'; +/* Register our fantastic module. */ var eventManApp = angular.module('eventManApp', [ 'ngRoute', 'eventManServices', @@ -7,6 +8,7 @@ var eventManApp = angular.module('eventManApp', [ ]); +/* Directive that can be used to make an input field react to the press of Enter. */ eventManApp.directive('ngEnter', function () { return function (scope, element, attrs) { element.bind("keydown keypress", function (event) { @@ -21,6 +23,7 @@ eventManApp.directive('ngEnter', function () { }); +/* Configure the routes. */ eventManApp.config(['$routeProvider', function($routeProvider) { $routeProvider. @@ -51,5 +54,6 @@ eventManApp.config(['$routeProvider', otherwise({ redirectTo: '/events' }); -}]); + } +]); diff --git a/angular_app/js/controllers.js b/angular_app/js/controllers.js index 23cf34a..b8fb2ad 100644 --- a/angular_app/js/controllers.js +++ b/angular_app/js/controllers.js @@ -4,6 +4,7 @@ var eventManControllers = angular.module('eventManControllers', []); +/* A controller that can be used to navigate. */ eventManControllers.controller('navigation', ['$location', function ($location) { this.go = function(url) { @@ -26,6 +27,7 @@ eventManControllers.controller('EventDetailsCtrl', ['$scope', 'Event', '$routePa if ($routeParams.id) { $scope.event = Event.get($routeParams); } + // store a new Event or update an existing one $scope.save = function() { if ($scope.event.id === undefined) { $scope.event = Event.save($scope.event); @@ -50,6 +52,8 @@ eventManControllers.controller('PersonDetailsCtrl', ['$scope', 'Person', '$route if ($routeParams.id) { $scope.person = Person.get($routeParams); } + // store a new Person or update an existing one + $scope.save = function() { $scope.save = function() { if ($scope.person.id === undefined) { $scope.person = Person.save($scope.person); diff --git a/angular_app/js/services.js b/angular_app/js/services.js index 334fc69..35a3d46 100644 --- a/angular_app/js/services.js +++ b/angular_app/js/services.js @@ -1,7 +1,9 @@ 'use strict'; +/* Services. */ var eventManServices = angular.module('eventManServices', ['ngResource']); + eventManServices.factory('Event', ['$resource', function($resource) { return $resource('events/:id', {id: '@_id'}, { From 06eb4c550bac9118107a3fba62bf9fb5325e7748 Mon Sep 17 00:00:00 2001 From: Davide Alberani Date: Sun, 22 Mar 2015 09:36:32 +0100 Subject: [PATCH 06/10] add license --- angular_app/index.html | 15 +++++++++++++++ angular_app/js/app.js | 17 ++++++++++++++++- angular_app/js/controllers.js | 4 +++- angular_app/js/services.js | 2 +- backend.py | 13 +++++++++++++ eventman_server.py | 13 +++++++++++++ 6 files changed, 61 insertions(+), 3 deletions(-) diff --git a/angular_app/index.html b/angular_app/index.html index 3abe275..28f2e01 100644 --- a/angular_app/index.html +++ b/angular_app/index.html @@ -15,6 +15,21 @@ + +
diff --git a/angular_app/js/app.js b/angular_app/js/app.js index eaeb50d..17cbc81 100644 --- a/angular_app/js/app.js +++ b/angular_app/js/app.js @@ -1,6 +1,21 @@ 'use strict'; +/* + Copyright 2015 Davide Alberani + RaspiBO -/* Register our fantastic module. */ + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + + +/* Register our fantastic app. */ var eventManApp = angular.module('eventManApp', [ 'ngRoute', 'eventManServices', diff --git a/angular_app/js/controllers.js b/angular_app/js/controllers.js index b8fb2ad..c1c6ae0 100644 --- a/angular_app/js/controllers.js +++ b/angular_app/js/controllers.js @@ -1,6 +1,8 @@ 'use strict'; -/* Controllers */ +/* Controllers; their method are available where specified with the ng-controller + * directive or for a given route (see app.js). They use some services to + * connect to the backend (see services.js). */ var eventManControllers = angular.module('eventManControllers', []); diff --git a/angular_app/js/services.js b/angular_app/js/services.js index 35a3d46..84e995f 100644 --- a/angular_app/js/services.js +++ b/angular_app/js/services.js @@ -1,6 +1,6 @@ 'use strict'; -/* Services. */ +/* Services that are used to interact with the backend. */ var eventManServices = angular.module('eventManServices', ['ngResource']); diff --git a/backend.py b/backend.py index e6dcf2e..82b87c1 100644 --- a/backend.py +++ b/backend.py @@ -1,6 +1,19 @@ """Event Man(ager) database backend Classes and functions used to manage events and attendants database. + +Copyright 2015 Davide Alberani + RaspiBO + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. """ import pymongo diff --git a/eventman_server.py b/eventman_server.py index 8fd05ea..b64db30 100755 --- a/eventman_server.py +++ b/eventman_server.py @@ -2,6 +2,19 @@ """Event Man(ager) Your friendly manager of attendants at a conference. + +Copyright 2015 Davide Alberani + RaspiBO + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. """ import os From 0a2681a7e4e2db9925fc76481ac2e21e15f4245d Mon Sep 17 00:00:00 2001 From: Davide Alberani Date: Sun, 22 Mar 2015 10:12:44 +0100 Subject: [PATCH 07/10] technological stack --- README.md | 56 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 36 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index b1cfae2..c97f910 100644 --- a/README.md +++ b/README.md @@ -11,10 +11,45 @@ No, this project is not ready, yet. I'll let you know when I'm finished experimenting with it and you can contribute. +Technological stack +=================== + +- [AngularJS](https://angularjs.org/) for the webApp +- [Bootstrap](http://getbootstrap.com/) (plus [jQuery](https://jquery.com/)) for the eye-candy +- [Tornado web](http://www.tornadoweb.org/) as web server +- [MongoDB](https://www.mongodb.org/) to store the data + +The web part is incuded; you need to install Tornado, MongoDB and the pymongo module on your system (no configuration needed). + + +Coding style and conventions +============================ + +It's enough to be consistent within the document you're editing. + +I suggest four spaces instead of tabs for all the code: Python (**mandatory**), JavaScript, HTML and CSS. + + +Install and run +=============== + + wget https://bootstrap.pypa.io/get-pip.py + sudo python get-pip.py + sudo pip install tornado + sudo pip install pymongo + cd + git clone https://github.com/raspibo/eventman + cd eventman + ./eventman_server.py --debug + + +Open browser and navigate to: http://localhost:5242/ + + License and copyright ===================== -Copyright 2015 Davide Alberani +Copyright 2015 Davide Alberani RaspiBO Licensed under the Apache License, Version 2.0 (the "License"); @@ -27,22 +62,3 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -Install and run -=============== - -wget https://bootstrap.pypa.io/get-pip.py - -sudo python get-pip.py - -sudo pip install tornado - -cd - -git clone https://github.com/raspibo/eventman - -cd eventman - -./eventman_server.py - - -Open browser and navigate to: http://localhost:5242/ From af6b5417ff524855cb8d654c9c16488e0a9d8389 Mon Sep 17 00:00:00 2001 From: Davide Alberani Date: Sun, 22 Mar 2015 10:17:04 +0100 Subject: [PATCH 08/10] docstrings --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index c97f910..4c1df45 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,8 @@ It's enough to be consistent within the document you're editing. I suggest four spaces instead of tabs for all the code: Python (**mandatory**), JavaScript, HTML and CSS. +Python code documented following the [Sphinx](http://sphinx-doc.org/) syntax. + Install and run =============== From 7bfcb3f956dc110156f17cba46abcd9bf7332e5c Mon Sep 17 00:00:00 2001 From: Davide Alberani Date: Sun, 22 Mar 2015 11:07:08 +0100 Subject: [PATCH 09/10] notes about the development --- README.md | 4 +++- backend.py | 2 +- eventman_server.py | 2 +- 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 4c1df45..f8ecaa5 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ Event Man(ager) =============== -Manage attendants at an event. +Your friendly manager of attendees at a conference. Notice ====== @@ -10,6 +10,8 @@ No, this project is not ready, yet. I'll let you know when I'm finished experimenting with it and you can contribute. +See the DEVELOPMENT.md file for more information about how to contribute. + Technological stack =================== diff --git a/backend.py b/backend.py index 82b87c1..e46814f 100644 --- a/backend.py +++ b/backend.py @@ -1,6 +1,6 @@ """Event Man(ager) database backend -Classes and functions used to manage events and attendants database. +Classes and functions used to manage events and attendees database. Copyright 2015 Davide Alberani RaspiBO diff --git a/eventman_server.py b/eventman_server.py index b64db30..23636be 100755 --- a/eventman_server.py +++ b/eventman_server.py @@ -1,7 +1,7 @@ #!/usr/bin/env python """Event Man(ager) -Your friendly manager of attendants at a conference. +Your friendly manager of attendees at a conference. Copyright 2015 Davide Alberani RaspiBO From 1bb9d144ce4f4dd097abda2a45b80ef36723a619 Mon Sep 17 00:00:00 2001 From: Davide Alberani Date: Sun, 22 Mar 2015 11:08:23 +0100 Subject: [PATCH 10/10] slogan! --- README.md | 2 +- eventman_server.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f8ecaa5..6e3216f 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ Event Man(ager) =============== -Your friendly manager of attendees at a conference. +Your friendly manager of attendees at an event. Notice ====== diff --git a/eventman_server.py b/eventman_server.py index 23636be..547b986 100755 --- a/eventman_server.py +++ b/eventman_server.py @@ -1,7 +1,7 @@ #!/usr/bin/env python """Event Man(ager) -Your friendly manager of attendees at a conference. +Your friendly manager of attendees at an event. Copyright 2015 Davide Alberani RaspiBO