catalog package¶
Submodules¶
catalog.app module¶
catalog.auth module¶
This is the auth, or Authorization module for the Catalog app. The module provides methods for Authorizing the app to connect/disconnect to/from a user’s Google+ profile.
-
catalog.auth.CLIENT_ID¶ The Client Secret for the Catalog App. This file is generated from the app’s credentials using the Google Development Console. It is not included with the repository for the purpose of security. Running the app will require the creation of the client secret using the previously mentioned Development Console. The client_secret.json file needs to be in the same directory as this module.
-
catalog.auth.ConnectGoogle(request)[source]¶ Process the Request to the App for logging in to Google+.
Parameters: request (Request) – Contains the information for requesting login to Google+
Returns: returnValues
Detailed Description of the possible values of the returned variable. Describe contents and format of returned values. Describe Usage.
Return type: Response
Raises: FlowExchangeError– The flow exchange setup establishing authorization- with the Google+ failed.
Examples
(optional) Describe how the function is used by providing examples here.
-
catalog.auth.DisconnectGoogle()[source]¶ Disconnect from Google by Revoking access to a User’s Google Profile
Returns: A varying response depending upon the success or failure in revoking the app’s usage of the logged in user’s Google Profile. Return type: Response Raises: TokenRevokeError– Google was unable to revoke the connection between this app and their Google profile.
-
catalog.auth.canAlter(userID)[source]¶ Confirms that the user specified by the given user id is the one currently in the login_session.
Parameters: userID (int) – An ID corresponding to a User record in the database. Returns: True if the specified user is also the currently authorized user in the login_session. False if it is a different user.
-
catalog.auth.createResponse(res, status)[source]¶ Create a response to a Request to one of the App’s endpoints.
When the routes for connecting/disconnecting to Google+ are called, this function will be used to send various responses to those requests.
Parameters: - res (object) – A response with information pertinent to a request for Connect and Disconnect to and from Google+
- status (int) – Depending upon the result of processing the request, this will indicate whether or not the request was successful.
Returns: A response in json format containing the data passed in via the res and status arguments.
Return type: Response
-
catalog.auth.createUser(login_session)[source]¶ Add a User to the database using the current information stored in the login session.
Parameters: - login_session (dict) – Dictionary containing information about the current
- session, including the user's profile information from Google+ (login) –
Returns: The user_id from the newly created record in the User table in the database.
Return type: int
-
catalog.auth.csrf_protect()[source]¶ Protect form submissions using a CSRF token.
If the token is found and validated, then the request will proceed.
Notes
This function is applied to a POST request before it is processed by any of the routes that would receive a POST.
The only POST request that can be made for an unauthenticated user is to connect to their Google+ profile.
Returns: In the event that a token is invalid the user will be sent a notice.
-
catalog.auth.generate_csrf_token()[source]¶ Generate A CSRF token for the User’s login session
Returns: Returns a the csrf_token for the currently logged in user. Return type: string
-
catalog.auth.generate_random_string()[source]¶ Create a 16 character long string containing randomly generated characters.
Returns: The Randomized string. Return type: string
-
catalog.auth.getLoginSessionState()[source]¶ Retrieve the Login Session’s state.
The State is assigned to the Login Session when a user logs in to the App. This is a specific string used to validate the session.
Returns: The state is generated upon user login and added to the login session and returned. Return type: string
-
catalog.auth.getSessionUserInfo()[source]¶ Return profile information for the user currently logged in.
Note
The profiles for the User records generated using the populator module obviously won’t have valid information related to Google+.
Returns: Basic profile information for the login_session user. Including: user_id: Their User record in the database. name: Their name (from their Google+ Profile) email: Their email (also taken from their Google+ Profile) Return type: dict
-
catalog.auth.getUserID(email)[source]¶ Retrieve a User record from the Database via their User id.
Note
Any information regarding usage or something the caller of the function should know when using it.
Parameters: user_id (int) – The key/primary key in the User table Returns: returns an instance of the models.User class populated with the user’s information. Return type: models.User Raises: NoResultFound– No user was found with the given email.
-
catalog.auth.getUserInfo(user_id)[source]¶ Retrieve a User record from the Database via their User id.
Note
Any information regarding usage or something the caller of the function should know when using it.
Parameters: user_id (int) – The key/primary key in the User table Returns: - returns an instance of the models.User class populated with
- the user’s information.
If no user is found, None is returned.
Return type: models.User Raises: NoResultFound– No user was found with the given user id.
catalog.database module¶
This is the database module for the Catalog app. The module provides a method for initialzing the database connection/session.
-
catalog.database.engine¶ The SQLAlchemy connection to the app’s database.
-
catalog.database.DBSession¶ The SQLAlchemy database session for making queries against the models and data conatined in the database.
-
catalog.database.session¶ Provides a scoped session of the above session.
-
catalog.database.Base¶ The Base class of each class in the Database Model. Uses the
-
scoped session to provide the query property to each class that inherits
-
from it.
-
catalog.database.app¶ The Flask App instance, provides the Database directive.
catalog.models module¶
This is the models module for the Catalog app. The module creates the ORM model connecting classes to tables in the database.
The classes are User, Category and Item
The traits module is used for generating forms and views of instances of each class/object.
A model uses Default Traits for plain views that offer no editing and a traits property for views that do.
-
class
catalog.models.Category(**kwargs)[source]¶ Bases:
sqlalchemy.ext.declarative.api.BaseItems in the Catalog are each assigned to a Category that pertains to the activity or sport associated with the item.
-
name¶ string
The Category name.
-
id¶ integer
The primary key/id
-
user_id¶ integer
The user id of the Category’s creator.
-
items¶ relationship
Defines the list of items in the Category.
-
query¶ Query
Shortcut for Querying the Category table
-
static
categories()[source]¶ List of all Category names in the table.
Returns: A list containg the names of each Category int the table.
-
creator¶ The name of the user who created the Category in the Table.
Returns: The user name who created the Category. Return type: string
-
static
defaultTraits()[source]¶ The default traits of Category
Returns: A list of Trait objects describing the attributes of a Category that can be viewed.
-
static
findByID(id)[source]¶ Find a Category in the table using its id.
Parameters: id (int) – The primary key or id of the Category in the table. Returns: A Category object with the given id.
-
static
findByName(name)[source]¶ Find a Category in the table by its name.
Parameters: name (string) – The Category name to find. Returns: A Category record from the database that has the specified name.
-
id
-
items
-
name
-
query= <sqlalchemy.orm.query.Query object>
-
serialize¶ Serialize the properties of a Category instance.
Returns: A Dictionary describing key attributes of a Category instance Return type: dict
-
traits()[source]¶ The attributes and values of an instance of the Category class.
When presenting a view to a web user, the traits are parsed and displayed in a form or list in a format determined by the type of each attribute’s associated Trait Class.
Returns: A list containing the Traits for each attribute to be displayed in a view of a Category instance.
-
user_id
-
-
class
catalog.models.Item(**kwargs)[source]¶ Bases:
sqlalchemy.ext.declarative.api.BaseItems in the Catalog are each created by a User and belong to a specific Category.
-
name¶ string
The Item name.
-
id¶ integer
The primary key/id
-
cat_id¶ integer
-
user_id¶ integer
The primary key/id for the Item’s creator
-
picture¶ string
The url to the item’s picture in the local
-
filesystem.
-
description¶ string
The Item’s description.
-
dateCreated¶ date
The Date the Item was created.
-
query¶ Query
Shortcut for Querying the Item table.
-
User¶
-
cat_id
-
category¶
-
creator¶ The user name of the Item’s creator.
Returns: The name of the user that created the Item record. Return type: string
-
dateCreated
-
static
defaultTraits()[source]¶ The attribute names for the Item Class.
When creating a new item via a form, the default traits are used to describe the properties that define an Item in the Catalog.
Returns: Each Trait in the list describes a property of the Item to be created. The Trait’s type changes how it is rendered when presented to the user.
-
describe¶ Describe an Item by its name and the name of its Category.
Returns: A descriptive string including the Item name and Category. Return type: string Example
“Stick (Hockey)”
-
description
-
id
-
name
-
picture
-
query= <sqlalchemy.orm.query.Query object at 0x00000000054E4DD8>
-
serialize¶ Serialize the properties of a Item instance.
Returns: A Dictionary describing key attributes for an Item instance. Return type: dict
-
traits(isEdit=False)[source]¶ The attributes and values of an instance of the Item class.
When presenting a view to a web user, the traits are parsed and displayed in a form or list in a format determined by the type of each attribute’s associated Trait Class.
Notes
Traits for generating a form for view and edit. An ImageUploadTrait is added for the edit view (specify isEdit as True).
Parameters: - isEdit (Boolean) – True means an edit view will be generated
- the Traits of the Item. False means that it will just display (from) –
- values of each Trait. (the) –
Returns: A list containing the Traits for each attribute to be displayed in a view of an Item instance.
If isEdit is True a Trait will be included that allows the user to upload an Image for the item. Otherwise, the Item attributes will be displayed as a list of property name/value.
-
user_id
-
-
class
catalog.models.User(**kwargs)[source]¶ Bases:
sqlalchemy.ext.declarative.api.BaseUsers of the Catalog are each assigned a User record that is associated with the Items and Categories they create, and by extension, can edit and delete. Their profile information is pulled from their Google+ profile.
-
name¶ string
The User name.
-
id¶ integer
The primary key/id
-
email¶ string
The User’s email address.
-
picture¶ string
The url to the user’s picture in the local
-
filesystem or to the url of their profile picture from Google+
-
items¶ relationship
Defines the list of items the User has created.
-
categories¶ relationship
List of Categories created by the User.
-
query¶ Query
Shortcut for Querying the User table.
-
categories
-
static
defaultTraits()[source]¶ The attribute names for the User Class.
When creating the new user via a form, the default traits are used to describe the properties that a user needs to provide information for.
Returns: A list containing the Traits for each attribute to be displayed in a form for creating an instance of the User class.
-
email
-
id
-
items
-
name
-
static
nameByID(user_id)[source]¶ Retrieve a user’s name by their user id.
Parameters: user_id (int) – The primary key of the User in the table. Returns: The name of the user associated with the given user id. Return type: string
-
picture
-
serialize¶ Serialize the properties of a User instance.
Returns: A Dictionary describing key attributes of a User instance Return type: dict
-
traits()[source]¶ The attributes and values of an instance of the User class.
When presenting a view to a web user, the traits are parsed and displayed in a form or list in a format determined by the type of each attribute’s associated Trait Class.
Returns: A list containing the Traits for each attribute to be displayed in a view of a User instance.
-
catalog.urls module¶
Generate urls for a Flask App for CRUD and list operations.
This module is used to generate routes for a Flask application given:
1. The lowercase name of the class that corresponds to an SQLAlchemy Data Model.
- The id or primary key for an instance of that class in the database.
-
class
catalog.urls.Urls(suffix, object_id=0)[source]¶ Bases:
object- Generate a series of urls that are paths to routes for listing, viewing,
editing, deleting or creating instances of a specified class.
- Notes:
- see http://flask.pocoo.org/docs/0.10/templating/#context-processors for more about context processors
- Args:
- suffix (string): Lowercase name of a class in the database.
- (i.e. category, user, item)
- key (integer): A primary key value in the database that matches
- a record for the class in suffix,
- Attributes:
- suffix (string): Lowercase representation of a class in the database.
- (Category, User, Item)
- key (integer): A primary key value in the database that matches
- a record for the class in suffix,
Each of these routes refers to an operation on a record from the database table that matches the value of suffix and primary key in key.
deleteUrl (string): root/suffix/key/delete editUrl (string): root/suffix/key/edit viewUrl (string): root/suffix/key newUrl (string): root/suffix/add listUrl (string): root/suffix + “s” listString (string): “Back to Suffix” + “s.”
Examples
For an app with /catalog as the root path/url,
urls = makeUrls(‘item’, 1) urls would return an object with the following properties/values.
urls.suffix “item” urls.key 1 urls.deleteUrl /catalog/item/1/delete urls.editUrl /catalog/item/1/edit urls.viewUrl /catalog/item/1 urls.newUrl /catalog/item/add urls.listUrl /catalog/items urls.listString “Back to Items.”
-
deleteUrl¶
-
editUrl¶
-
key¶
-
listString¶
-
listUrl¶
-
newUrl¶
-
suffix¶
-
viewUrl¶
catalog.views module¶
This is the views module for the Catalog app. The module provides routes to create a RESTful api to create, read, update and delete records for the following elements in the Catalog:
User, Category and Item
There are routes to authorize a user using the OAuth2 api provided by Google to connect and disconnect a user via their Google+ profile.
There are two endpoints provided to return the entirety of the Catalog in JSON or XML.
The module also includes a handful of context processor’s for its flask app. These functions allow the jinja2 templates, which provide the views to the web client, with means of accessing variables and functions in the Python modules and code.
-
catalog.views.allowed_image(filename)[source]¶ Determine if the specified file has the proper extension to be classified as an image.
Note
From flask docs, checks that uploaded images have specific file extensions http://flask.pocoo.org/docs/0.10/patterns/fileuploads/
Parameters: filename (string) – The filename to be validated as an acceptable image type. Returns: True if the file is a proper image file, based upon its extension. False if it is not considered a valid image type.
-
catalog.views.catalogJSON()[source]¶ JSON endpoint that returns information about the entire Catalog.
Returns: A GET request returns the Catalog’s information in JSON
-
catalog.views.catalogXML()[source]¶ XML endpoint that returns information about the entire Catalog.
Returns: A GET request returns the Catalog’s information in XML
-
catalog.views.delItem(item_name)[source]¶ Retrieve the view for Deleting an Item in a Category.
Requires a user to be authenticated and to have created the item.
Notes
The actual deletion operation, when a POST request is sent, is performed by the deleteItem function.
Parameters: - category_name (string) – The Category name of the Item to delete.
- item_name (string) – The name of the Item to delete.
Returns: A GET request presents the user with choices for deleting the Item or canceling the operation.
-
catalog.views.deleteCategory(key)[source]¶ Allow an Authorized User to delete a new Category or Process the deletion of a Category.
Parameters: key (int) – The primary key of the category. Returns: For a GET operation returns a View querying whether the user wants to delete the Category or cancel and go back to viewing it. A successful POST request deletes the Category and redirects to the list of Categories.
-
catalog.views.deleteItem(key)[source]¶ Delete an Item selected by its primary key/id.
Requires a user to be authenticated and to have created the item.
Parameters: key (int) – The primary key of the Item to delete. Returns: A GET request presents the user with choices for deleting the Item or canceling the operation.
-
catalog.views.deleteUser(key)[source]¶ Present the Web User with a Delete View for the their User account.
Parameters: key (int) – An ID corresponding to a User record in the database. Returns: For a GET operation returns a Web View containing buttons for canceling or submitting the delete user request. A successful POST request would delete the User’s record, sign them out and revoke the app’s authorization to use their Google profile
-
catalog.views.editCatItem(category_name, item_name)[source]¶ Edit an Item in a Category.
Requires a user to be authenticated and to have created the item.
Parameters: - category_name (string) – The Category of the Item to edit.
- item_name (string) – The name of the Item to Edit.
Returns: A GET request presents the user with a form for editing an Item.
A POST request processes the user’s input from the form and updates the item.
-
catalog.views.editCategory(key)[source]¶ Allow an Authorized User to edit a new Category or Process the form for editing a Category.
Parameters: key (int) – The primary key of the category. Returns: For a GET operation returns a Web View containing a form for altering data for the category. A successful POST request directs presents a View of the new Category.
-
catalog.views.editItem(key)[source]¶ Edit an Item in a Category.
Requires a user to be authenticated and to have created the item.
Parameters: key (int) – The primary key of the Item to Edit. Returns: A GET request presents the user with a form for editing an Item. A POST request processes the user’s input from the form and updates the item.
-
catalog.views.editUser(key)[source]¶ Present the Web User with an Edit View for the their User account.
Parameters: key (int) – An ID corresponding to a User record in the database. Returns: For a GET operation returns a Web View containing a form for editing data for the user. A successful POST request directs presents the updated Record view.
-
catalog.views.hasattr_processor()[source]¶ Provide templates with the ability to check if a python object contains the specified attribute
Parameters: - o (object) – The object to check.
- attr (string) – The name of the attribute to look for in object, o.
Returns: True if object o has the attribute. False if there is no attribute with the value of attr in object o.
-
catalog.views.itemJSON(key)[source]¶ Return information about a Catalog Item in JSON.
Parameters: key (int) – The primary key of the item to retrieve. Returns: A GET request returns information about an item in JSON
-
catalog.views.listCategory()[source]¶ A View containing the list of Categories.
Returns: Presents the user with a list of all user Categories
-
catalog.views.listCategoryItem(category_name)[source]¶ List all Items in a category.
Parameters: category_name (string) – The category of items to be viewed. Returns: A GET request presents the user with the list of all items belonging to the specified category.
-
catalog.views.listItem()[source]¶ List all Items in the catalog.
Returns: A GET request presents the user with the list of all catalog items.
-
catalog.views.listUser()[source]¶ Present the Web User with an Edit View for the their User account.
Returns: Presents the user with a list of all user Names
-
catalog.views.newCategory()[source]¶ Allow an Authorized User to add a new Category or Process the form for adding a new Category.
Returns: For a GET operation returns a Web View containing a form for entering data for the new user. A successful POST request directs presents a View of the new Category.
-
catalog.views.newItem()[source]¶ This route is used behind the scenes to view an item. It forwards the request on to viewCatItem. Requires a user to be authenticated.
Notes
This route could be changed to reflect which category it will be in.
Returns: A GET request presents the user with a form for creating a new Item. A POST request processes the user’s input from the form and adds the new item.
-
catalog.views.newUser()[source]¶ Present an Authorized Web User with a View for adding a new user.
Returns: For a GET operation returns a Web View containing a form for entering data for the new user. A successful POST request directs presents a View of the new Record.
-
catalog.views.processImageUpload(image)[source]¶ Process an uploaded image. If it’s a valid file type, then save the file and return the local url.
Parameters: image (file) – A file passed via a request that was submitted via a Web Form. Returns: The local path to the file for the image, this provides a url that can be referred to in a database record.
-
catalog.views.viewCatItem(category_name, item_name)[source]¶ Present a view of an item that belongs to a specific Category
Note
This route is typically redirected to behind the scenes. Which allows for a legible URL to be seen by the user. The item record already contains it’s category id.
Returns: A Web view containing information about an item, including its Category in the URL displayed in the browser.
-
catalog.views.viewCategory(key)[source]¶ A View of a specific Category’s record.
Parameters: key (int) – The primary key of the category. Returns: Presents the user with a list of all Categories