The Home Library App was created as Portfolio Project #3 (Python Essentials) for Diploma in Full Stack Software Development at Code Institute. It allows users to manage their personal book libraries, view, add, edit, and remove books.
Project purpose was to build a command-line python application that allows user to manage a common dataset about a particular domain.
- Project
- User Experience (UX/UI)
- Logic and features
- Technology
- Testing
- Deployment
- Possible future development
- Credits
I chose to develop an application that can be used in real life. Home Library allows users to manage their personal book libraries. Application offers such functionalities as: viewing book database, adding/editing and removing books. User can display details of every database entry and also sort database in chosen order.
Application should have clean and intuitive user interface and offer easy access and navigation to all functionalities.
To achieve the strategy goals I implemented following features:
- clean user interface for easy navigation and readability,
- menu with easy acces to all features and possibility to exit program,
- colours in terminal to give user feedback depends on his actions,
- reliable and quick connection with database provided by Google,
- customised terminal display page for better visual experience,
As a program owner/developer I would like to:
- create application that has real life usage,
- create application that is easy to use and intuitive to navigate,
- create application with clean, good looking and accesible interface,
- provide user a feedback to every input and action,
- decide what kind of user input is allowed and valid,
- create bug free application.
As a user I would like to:
- be able to clearly understand application's purpose from the first contact,
- be able to use program in real life,
- be able to easily navigate the program and access all features,
- be able to receive feedback to actions taken,
- be able to decide what to do next, what features to use,
- be able to quit program,
- avoid any errors/bugs during using the app.
Colour palette was selected using coolors.co generator and has been extracted from the backgroud picture used in terminal view HTML page. Colour of the "run program" button was adjusted to match the backgroud.
Terminal outputs are displayed in high-contrast colours over black background for better readability and accesibillity. Standard prompts are yellow, book addition and edit inputs are blue, warnings red. Confirmation messages and menus are green. Bigger chunks of data coming from the database are printed in standard white colour to be non-distractive for the user.
Screenshots presenting terminal and colour outputs are available in Features section.
Starting screen of the app with logo and menu:
A flow diagram of the logic behind the application was created using Lucid Chart.
For PDF version click here
Google Sheets service is used to store project's database in the spreadsheet. There are two worksheets, one to store book entries and second to store information about sorting methods.
Worksheet "library" is used to store book entries:
Main table consists of six colums: ID, title, author, category, status and description. The ID value works as a ordinal number for database. It's not unique and fix value assigned to a book.
Each column has individually assigned value that represents maximum length of the string that can be input by user. It's 2, 24, 18, 12, 8 and 200 characters respectively. Exceeding that limit results in error and feedback sent to the user. This limitation is necessary to correctly display the table in the terminal which maximum length is 80 characters.
The ID column value is assigned automatically when new book is added and also all ID values are renumbered when book is removed.
Worksheet "config" is used to store values for default and optional sorting method:
Start screen of the application consists of ASCII logo, welcome message and main menu with 7 options. User input is validated.
This feature allows user to add new entry to the library. Following details can be added: title, author, category, reading status and description. The ID number is generated automaticaly for a new record.
If database is empty, user is asked to add his first book in order to be able to use other app features.
There is additional feature implemented here. It checks if title string entered by user contains prefix "the". It converts the string to format "Title, The" and shows user converted title.
Every input is validated, it should be at least 3 characters long.
Each book detail has individually set maximum length. Max. title length is 24 characters.
Input can't be empty.
Title can't start with special character.
User is asked to chose reading status of the book by pressing "1" or "2".
This field is validated.
Similar validation method is applied to other required inputs. Upon successfull entry of all details user is asked to confirm book addition.
User receives confirmation when book is added. Automatic sorting of the database is applied and all book's are renumbered with ID. The purpose of this operation is to keep ascending numerical order in the database when book is added or removed. ID number in this case is used only as record's ordinal number. I realise that in more complicated database each entry would be assigned to unique, fix number but I decided that in Home Library app sorting by title or by author is more useful to the user.
This function allows user to edit every book's detail. First, user is asked to choose book to edit and when book's detailed view is presented, user can choose what detail he wants to edit. It is also possible to return to main menu. The input is validated.
The function works in a similar way as add book function, but it updates exisiting entries.
App checks title if prefix "the" was entered. If this happens, it converts the string to format "Title, The".
User receives confirmation and updated value is shown in the table printed to terminal.
This function allows user to delete selected book from the database. User is asked to select book to delete and then need to confirm his choice. The input is validated.
The status of the book is checked and printed in the terminal. Green message is printed if book's status is READ and red message if NOT READ. The input is validated.
Confirmation is shown when book is deleted.
This function allows user to view all database records. The table max. width is limited to 79 characters to comply with PEP8 and match the terminal mockup page.
This user allows user to chose database sorting method. Books are always sorted in alphabetical, ascending order but user can chose column to sort by - by title or by author.
Config worksheet stores values for both default and optional method. User can choose method opposite to currently set. The ID values are automatically renumbered in order to keep ascending order. I used this logic in order to avoid need to sort database each time when program starts or ends. It would take time to load application and there is no guarantee that user properly terminate the application allowing app to save changes. Default and optional method values are updated in config worksheet each time sorting is done. User can also decide to go back to previous screen. Input is validated.
Confirmation is printed in the terminal when operation is finished.
This function allows user to view all details of the selected book.
Description maximum length is limited to 200 characters, that's why it's displayed under the table. The text is wrapped to 79 characters in line. The input is validated.
This function terminates the program. User is asked to confirm his choice, the input is validated. Application generates and displays random literature-related quote.
Exit screen is displayed when user confirms exit. It contains the credits, social media links and another feature which is next read suggestion. It works only if in database is at least one book with status "NOT READ".
- Python - high-level, general-purpose programming language.
- Markdown - markup language used to write README and TESTING documents.
-
Coolors.co - was used to create colour palette for terminal display page.
-
Favicon.io - tool used to create favicon.
-
Font Awesome: - Font Awesome icons were used for social links in terminal display page.
-
Git - Git was used for version control by utilizing the Gitpod terminal to commit to Git and Push to GitHub.
-
GitHub - GitHub is used to store the project's code after being pushed from Git.
-
Google Sheets API - was used to connect with the database made of the spreadsheet.
-
Heroku - online app used to deploy project.
-
LucidChart - was used to create flow diagram.
-
Pexels.com - was used to source bacground picture for terminal display page.
-
PyCharm - Python IDE used to write the app.
-
Text ASCII Art Generator - used to create app logo in ASCII format.
-
WebAIM - online tool to check colour contrast/accesibility.
-
gspread - used for control Google Sheets API by python.
-
OAuthLib - required to manage HTTP request and authenticate to Google Sheets API.
-
PrettyTable - python library for easily displaying tabular data in a visually appealing ASCII table format.
-
colorama - used to color terminal outputs.
-
os - built-in pythod module - used to write clear_terminal function.
-
textwrap - built-in python module - used to wrap lines over 79 char to next line e.g. long book description.
-
random - built-in python module - used to generate random quote and random book on exit screen.
WebAIM online tool was used to check terminal colour contrast. All used colours passsed the test satisfactory.
PEP8CI app was used to lint the code. All modules are clear, no errors found. In app_menu.py linter shows couple of warnings regarding whitespaces and escape character in app logo created in "text to ASCII generator". This doesn't affect any functionalities and code is interpreted as intended, terminal output is displayed as intended.
I noticed that IDEs (VSC and PyCharm) and PEP8CI linter ask to leave last line of the code empty, however GitHub ignores that empty line.
Details of manual testing can be found in TESTING.md file
-
Issue #1: During the edit I made indentation error and misplaced last "break" instruction of the code presented on screenshot below. That caused infinite loop to work in the backgroud without any terminal output. It was a major issue as all main program features generated an Google Sheets API error code 429 - "To many requests HTTP status code response". I thought that I exeeded Google Sheets Quoata per user/per minute/per project but after checking logs and quotas in Google Cloud Console I knew that something else caused an error. I finally managed to find the mistake. It wasn't obvious as function was meant to work "in the bacground" without any terminal output as long as there are records in database. Database wasn't empty at that time so the message hasn't been printed in the terminal.
-
Solution: Putting "break" instruction in the correct place, that allows to "escape" from the while loop.
-
Issue #2: During manual testing there was a bug found. Terminal output (red warning message on the screenshot) wasn't displayed as intended.
-
Solution: Line break character was put in correct place.
-
Code Institute template was used to create GitHub public repository home-library-app. In template repository I clicked on "use this template" --> "create new repository", I chose repository name and clicked on the green button "Create repository from template".
-
I cloned repository to my local machine using GitHub Desktop and opened it in PyCharm IDE.
-
I developed programm, often commiting changes using terminal commands:
- git add .
- git commit -m "Do something"
- git push
-
I made sure that all my libraries and packages are listed in requirements.txt.
-
When program was ready for further deployment I visited heroku.com website to deploy on heroku.
-
I visited https://heroku.com/ and opened dashboard. Then I clicked button "New" and selected "Create new app" button.
-
I entered my app name as "home-library-app-ci", chose region to Europe and clicked on "Create app" button
- The next step was to go to "Deploy" tab and then to "Deployment method" section to authorize and connect my GitHub account.
- Upon succesfull connection I selected main branch from "home-library-app" repository.
- Then I went to "Settings" tab...
- ... and next to "Buildpacks" section. In the next step I added pyhton and nodejs buildpacks. Order here is very important.
-
In the next step I went to "Config Vars" section and added KEY "CREDS" - that maches my token name defined in python constant in api/google_sheets_api.py - with value of my credentials token (copy all and paste).
-
I added key "PORT" with value "8080" and save changes.
- In the next step I went back to "Deploy" tab and decided to use automatic deploys, however manual mode is also available to deploy chosen branch.
- The link to my deployed app was shown on screen: https://home-library-app-ci.herokuapp.com/
If I had more time or decide to develop app further I would add/improve following functionalities:
- adding/editing/removing book categories instead of typing desired name. That would help keep DB entries more consistent and make input easier for the user.
- add function to analyze description input by user and save it in database preserving capital letters for e.g. names, new sentences,
- add user accounts/multiple database,
- export database to external file in printable version.
- search database function
- Google Sheets API connection method is taken from Love Sandwiches CI Project and gspread documentation - in /api/google_sheets_api.py - line 10-19
- Stack Overflow - method used to write clear_terminal function in /utils/utils.py - line 26-32
- Goodreads.com - the source of the quotes used on app exit screen.
- Pexels.com - the source of the terminal page background picture.
- Text ASCII Art Generator - used to create app logo in ASCII format.
- Code Institute course and learning platform
- The book "Python Crash Course, 2nd Edition: A Hands-On, Project-Based Introduction To Programming"
- StackOverflow
- W3Schools
- Google Sheets API documentation
- Gspread documentation
- Documentation of python modules used in the project.
- My Mentor Reuben Ferrante for helpful feedback and guidance at all stages of the project.
- Code Institute Slack Community for being invaluable knowledge base.
- Home Library app was created for educational purpose only.