Skip to content

Commit 188450e

Browse files
author
App Generator
committed
README - Added Usage Info
1 parent 22d2fe8 commit 188450e

File tree

1 file changed

+250
-1
lines changed

1 file changed

+250
-1
lines changed

‎README.md‎

Lines changed: 250 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,250 @@
1-
# flask-pandas-dataframe
1+
# Flask Pandas Dataframe
2+
3+
Simple Flask project that loads a pandas (dataframe) into database and use SqlAlchemy to show the information in the browser.
4+
**Flask Pandas Dataframe** is a `one-file` project that migth help beginners to understand some basic Flask concepts:
5+
6+
- Create a simple Flask [app](/app.py)
7+
- Download a public [pandas](./titanic.csv) DF
8+
- Create a SQLite DB and a table to save the information
9+
- Load pandas in DB using a new `custom command`
10+
- Visualize the data in the browser
11+
12+
<br />
13+
14+
![Flask Pandas Dataframe - media file.](./media.png)
15+
16+
<br />
17+
18+
## Set up
19+
20+
```bash
21+
$ # Clone sources
22+
$ git clone https://github.com/app-generator/flask-pandas-dataframe.git
23+
$ cd flask-pandas-dataframe
24+
$
25+
$ # Virtualenv modules installation (Unix based systems)
26+
$ virtualenv env
27+
$ source env/bin/activate
28+
$
29+
$ # Virtualenv modules installation (Windows based systems)
30+
$ # virtualenv env
31+
$ # .\env\Scripts\activate
32+
$
33+
$ # Install dependencies
34+
$ pip3 install -r requirements.txt
35+
$
36+
$ # Create database via Flask CLI
37+
$ flask shell
38+
>>> from app import db # import SqlAlchemy interface
39+
>>> db.create_all() # create SQLite database and Data table
40+
>>> quit() # leave the Flask CLI
41+
$
42+
$ # Load the data into the database
43+
$ flask load-data titanic-min.csv
44+
$
45+
$ # Set the FLASK_APP environment variable
46+
$ (Unix/Mac) export FLASK_APP=run.py
47+
$ (Windows) set FLASK_APP=run.py
48+
$ (Powershell) $env:FLASK_APP = ".\run.py"
49+
$
50+
$ # Set up the DEBUG environment
51+
$ # (Unix/Mac) export FLASK_ENV=development
52+
$ # (Windows) set FLASK_ENV=development
53+
$ # (Powershell) $env:FLASK_ENV = "development"
54+
$
55+
$ flask run
56+
$ # access the app in the browser: http://localhost:5005
57+
```
58+
59+
<br />
60+
61+
## Dependencies
62+
63+
- [Flask](https://flask.palletsprojects.com/en/1.1.x/) - the framework used
64+
- [Pandas](https://pandas.pydata.org/) - an amazing `data analysis` library
65+
- [SQLAlchemy](https://www.sqlalchemy.org/) - Python SQL Toolkit and ORM
66+
- [Flask-SqlAlchemy](https://flask-sqlalchemy.palletsprojects.com/en/2.x/) - extension for Flask that adds support for SQLAlchemy
67+
- [Requests](https://pypi.org/project/requests/) - simple HTTP library.
68+
69+
```bash
70+
$ # Virtualenv modules installation (Unix based systems)
71+
$ virtualenv env
72+
$ source env/bin/activate
73+
$
74+
$ # Virtualenv modules installation (Windows based systems)
75+
$ # virtualenv env
76+
$ # .\env\Scripts\activate
77+
$
78+
$ # Install modules - SQLite Database
79+
$ pip3 install -r requirements.txt
80+
```
81+
<br />
82+
83+
## Env
84+
85+
```bash
86+
$ # Enable the DEBUG environment
87+
$ # (Unix/Mac) export FLASK_ENV=development
88+
$ # (Windows) set FLASK_ENV=development
89+
$ # (Powershell) $env:FLASK_ENV = "development"
90+
$
91+
$ # Set the FLASK_APP environment variable
92+
$ (Unix/Mac) export FLASK_APP=app.py
93+
$ (Windows) set FLASK_APP=app.py
94+
$ (Powershell) $env:FLASK_APP = ".\app.py"
95+
```
96+
97+
<br/>
98+
99+
## Download the data
100+
101+
The dataset is downloaded from a remote [location](https://static.appseed.us/data/titanic.txt) and saved [locally](./titanic.csv).
102+
103+
```python
104+
>>> import requests
105+
>>> import pandas as pd
106+
>>>
107+
>>> # Define the remote CSV file
108+
>>> csv_file = 'https://static.appseed.us/data/titanic.txt'
109+
>>>
110+
>>> # Download the file (via request library)
111+
>>> r = requests.get( csv_file )
112+
>>>
113+
>>> # Save the content to a new LOCAL file
114+
>>> f = open('titanic.csv', 'w')
115+
>>> f.write( r.content.decode("utf-8") )
116+
>>> f.close
117+
```
118+
119+
<br />
120+
121+
## Process data
122+
123+
The RAW dataset has ~900 rows and we can inspect it with ease using `pandas` library
124+
125+
```python
126+
>>> import pandas as pd
127+
>>>
128+
>>> df = pd.read_csv( 'titanic.csv' )
129+
>>> df
130+
PassengerId Survived Pclass Name Sex Age SibSp Parch Ticket Fare Cabin Embarked
131+
0 1 0 3 Braund, Mr. Owen Harris male 22.0 1 0 A/5 21171 7.2500 NaN S
132+
1 2 1 1 Cumings, Mrs. John Bradley (Florence Briggs Th... female 38.0 1 0 PC 17599 71.2833 C85 C
133+
2 3 1 3 Heikkinen, Miss. Laina female 26.0 0 0 STON/O2. 3101282 7.9250 NaN S
134+
3 4 1 1 Futrelle, Mrs. Jacques Heath (Lily May Peel) female 35.0 1 0 113803 53.1000 C123 S
135+
4 5 0 3 Allen, Mr. William Henry male 35.0 0 0 373450 8.0500 NaN S
136+
.. ... ... ... ... ... ... ... ... ... ... ... ...
137+
886 887 0 2 Montvila, Rev. Juozas male 27.0 0 0 211536 13.0000 NaN S
138+
887 888 1 1 Graham, Miss. Margaret Edith female 19.0 0 0 112053 30.0000 B42 S
139+
888 889 0 3 Johnston, Miss. Catherine Helen "Carrie" female NaN 1 2 W./C. 6607 23.4500 NaN S
140+
889 890 1 1 Behr, Mr. Karl Howell male 26.0 0 0 111369 30.0000 C148 C
141+
890 891 0 3 Dooley, Mr. Patrick male 32.0 0 0 370376 7.7500 NaN Q
142+
```
143+
144+
<br />
145+
146+
Return columns data types in the DataFrame: `df.dtypes`. This informationis used to design a `table` where is information is loaded.
147+
148+
```python
149+
>>> df.dtypes
150+
PassengerId int64
151+
Survived int64
152+
Pclass int64
153+
Name object
154+
Sex object
155+
Age float64
156+
SibSp int64
157+
Parch int64
158+
Ticket object
159+
Fare float64
160+
Cabin object
161+
Embarked object
162+
```
163+
164+
<br />
165+
166+
## Prepare the `storage`
167+
168+
Integrate SQLAlchemy and define a table to load the data.
169+
170+
```python
171+
# Store the Titanic sad stats
172+
class Data(db.Model):
173+
174+
passengerId = db.Column(db.Integer, primary_key=True )
175+
name = db.Column(db.String(250), nullable=False )
176+
survived = db.Column(db.Integer, nullable=False )
177+
sex = db.Column(db.String(10 ), default=None ) # name, female
178+
age = db.Column(db.Integer, default=-1 )
179+
fare = db.Column(db.Float, default=-1 )
180+
181+
# The string representation
182+
def __repr__(self):
183+
return str(self.passengerId) + ' - ' + str(self.name)
184+
```
185+
186+
<br />
187+
188+
Create the SQLite database and the new table via `Flask CLI`:
189+
190+
```bash
191+
$ flask shell
192+
App: app [development]
193+
Instance: D:\work\repo-learn\python\how-to\instance
194+
>>> from app import db
195+
>>> db.create_all()
196+
```
197+
198+
At this point, we can inspect the database using [SQLiteBrowser](https://sqlitebrowser.org/), an open-source and free editor for SQLite (the table is empty).
199+
200+
<br />
201+
202+
## Load Data
203+
204+
The information will be loaded into the database via a `custom command` = **load-data**. The command expects the `input file` as argument (CSV format).
205+
206+
```python
207+
# New import
208+
import click
209+
210+
...
211+
212+
# Custom command
213+
@app.cli.command("load-data")
214+
@click.argument("fname")
215+
def load_data(fname):
216+
''' Load data from a CSV file '''
217+
print ('*** Load from file: ' + fname)
218+
219+
# The functional part goes here
220+
...
221+
```
222+
223+
To check the command is properly coded we can type `flask --help` in the terminal:
224+
225+
```bash
226+
$ flask --help
227+
228+
Options:
229+
--version Show the flask version
230+
--help Show this message and exit.
231+
232+
Commands:
233+
load-data Load data from a CSV file <-- NEW Command
234+
routes Show the routes for the app.
235+
run Run a development server.
236+
shell Run a shell in the app context.
237+
```
238+
239+
<br />
240+
241+
## Links & Resources
242+
243+
- [Flask](https://flask.palletsprojects.com/en/1.1.x/) - the framework used
244+
- [Pandas](https://pandas.pydata.org/) - an amazing `data analysis` library
245+
- [AppSeed](https://appseed.us/) - for support annd more samples
246+
247+
<br />
248+
249+
---
250+
Flask Pandas Dataframe - Open-source sample provided by **AppSeed [App Generator](https://appseed.us/app-generator)**.

0 commit comments

Comments
 (0)